Reorganize code directories into python package organization

[penguinistakc]

Critical Package Structure Changes

1. Add Build System Configuration to pyproject.toml
   Missing [build-system] section
   Should specify build backend (recommend hatchling or setuptools)
2. Update Package Metadata in pyproject.toml
   Replace placeholder description: "Add your description here" → actual description
   Add missing fields:
   authors (name and email)
   license (you have a LICENSE file)
   keywords
   classifiers (Python versions, Development Status, License, Topic)
   urls (Homepage, Repository, Documentation, Issues)
   Consider renaming package to avoid PyPI conflicts (e.g., openstates-jurisdictions)
3. Populate init.py
   Currently empty
   Should export version and key public APIs
   Add package-level docstring
4. Add Console Scripts / Entry Points
   main.py should be available as a CLI command
   Add [project.scripts] section to pyproject.toml
5. Configure Package Data
   state_lookup.json needs to be included
   Add package data configuration for non-Python files
   Code Cleanup Changes
6. Move or Remove Root-Level Sample Files
   ohio_jurisdictions_CONSOLIDATED.py → move to sample_data or delete
   jurisdictions_sample.py → move to sample_data or delete
   These appear to be sample/test data, not production code
7. Handle Root-Level CSV Files
   ocdid_no_validation_asof_2026-02-01T02:55:04.887642+00:00.csv
   ocdid_no_validation_asof_2026-02-01T03:00:51.325043+00:00.csv
   Either add to .gitignore or move to data directory
8. Add Ruff Configuration
   Currently using ruff but no [tool.ruff] configuration in pyproject.toml
   Should specify linting rules, line length, exclude patterns
   Documentation Updates
9. Update Installation Instructions in README.md
   Add instructions for installing as a package
   Add pip install -e . or uv pip install -e . for dev mode
10. Create MANIFEST.in (if needed)
    Only if using setuptools and need to include non-code files
    May not be needed with proper pyproject.toml configuration
    Optional Improvements
11. Add Type Checking Configuration
    Add [tool.mypy] or [tool.pyright] configuration
    Already using type hints extensively
12. Versioning Strategy
    Consider dynamic versioning from git tags
    Or use version = "0.1.0" for initial release
13. Add all Exports
    In module init.py files to control public API
    Especially in src/models/init.py, src/utils/init.py
14. Consolidate dev dependencies
    Currently using [dependency-groups] (uv-specific)
    Consider adding [project.optional-dependencies] for broader compatibility

[penguinistakc]

Clarification on Items #3 and #13

After reviewing the implementation on the python-package-organization branch, items #3 and #13 carry library assumptions that conflict with the intended purpose of this package as a stand-alone application, not an importable library.

Item #3 — Populate __init__.py

The instruction to "export version and key public APIs" implies external consumers will import from src. For a stand-alone app, no external code does this — internal modules already import directly from each other (e.g., from src.models.source import SourceType), which is the correct pattern for an app.

Correct scope: src/__init__.py should contain only:

• The package-level docstring
• __version__ = "0.1.0"

Nothing else belongs there. In particular, re-exporting Division, Jurisdiction, SourceObj, etc. via __init__.py adds no value and introduces maintenance overhead (and in the current implementation, a runtime bug via the TYPE_CHECKING guard).

Item #13 — Add all Exports in __init__.py files

Same issue. Curating exports through __init__.py files in src/models/ and src/utils/ is a library convention for defining a stable public API surface. For a stand-alone app it is unnecessary — callers are always internal and already know the exact module path.

What actually matters for a stand-alone app

Item #4 (Console Scripts / Entry Points) is the most important item here. The [project.scripts] entry in pyproject.toml is what distinguishes an installable app from an installable library — it is what gives users a runnable CLI command after pip install. That should be the focus, not public API exports.