thingery

    ## Project overview
    
    **thingery** is a comprehensive physical and chemical reference data
    library. It bundles the periodic table (with all known isotopes),
    material properties, food nutrition data, measurement scales,
    physical constants, color definitions, and standardised protocols
    into a single installable Python package.
    
    thingery is designed to be:
    
    - **Comprehensive** — full periodic table, common materials, common
      foods, etc. all in one place.
    - **Structured** — every record is a typed dataclass with documented
      fields, so IDEs can autocomplete and type-checkers can validate.
    - **Scriptable** — first-class CLI plus a clean Python API.
    - **Offline-first** — no network calls at runtime, all data is
      bundled.
    
    ## Quick start
    
    ### Install
    
    ```bash
    pip install thingery
    ```
    
    ### Query an element
    
    ```python
    from thingery.elements import ELEMENTS
    
    # ELEMENTS is keyed by atomic number
    hydrogen = ELEMENTS[1]()
    print(hydrogen.name, hydrogen.symbol, hydrogen.atomic_mass)
    # Hydrogen H 1.008
    ```
    
    ### Use the CLI
    
    ```bash
    thingery --help
    thingery list-elements
    thingery element hydrogen
    thingery food apple
    ```
    
    ## Documentation
    
    Full documentation lives under `docs/` and is published at
    <https://www.solutionsbrewer.com/thingery/>. Key entry points:
    
    - [Quick start](docs/getting-started.md)
    - [Elements](docs/elements.md)
    - [Materials](docs/materials.md)
    - [Food](docs/food.md)
    - [Scales](docs/scales.md)
    - [CLI reference](CLI.md)
    - [API reference](docs/api/)
    
    ## Development
    
    ### Setup
    
    ```bash
    git clone https://github.com/solubrew/thingery.git
    cd thingery
    pip install -e ".[dev]"
    ```
    
    ### Run the tests
    
    ```bash
    pytest tests/ -v
    ```
    
    ### Lint
    
    ```bash
    ruff check thingery/
    ```
    
    ### Project layout
    
    ```
    thingery/
      elements/        # Periodic table (one module per element)
      materials/       # Material properties
      food/            # Nutrition data
      scales/          # Measurement scales
      numbers/         # Number theory helpers
      words/           # Word/lexical helpers
      models/          # Core dataclasses (Element, Isotope, etc.)
      cli.py           # Click CLI entry point
      constants.py     # Physical constants
      colors.py        # Color definitions
      scales.py        # Scale registry
      protocols.py     # Standard protocols
      _data_/          # Bundled data files
      institutions/    # Institutional reference data
    
    tests/
      unit/            # Unit tests
    
    docs/              # mkdocs documentation
    ```
    
    ### Adding a new element
    
    1. Create `thingery/elements/<lowercase_name>.py` with a dataclass
       subclass of `thingery.models.Element`. Each element module
       follows the same shape — see `thingery/elements/hydrogen.py`
       for the template.
    2. Add the import + class to `thingery/elements/__init__.py` so it's
       exported by name.
    3. Add the class to the `ELEMENTS` dict in
       `thingery/elements/__init__.py`.
    4. Add a test in `tests/unit/test_elements.py`.
    5. Update `CHANGES.md`.
    
    ### Adding a new material / food / scale
    
    Each subsystem follows the same pattern: a subdirectory containing
    one module per record, plus a registry in the subdirectory's
    `__init__.py`.
    
    ## License
    
    MIT — see `LICENSE`.