Metadata-Version: 2.4
Name: catalystcoop.cheshire
Version: 0.5.4
Summary: Replace this text with a one line description of the package.
Project-URL: Source, https://github.com/catalyst-cooperative/cheshire
Project-URL: Documentation, https://docs.catalyst.coop/cheshire
Project-URL: Issue Tracker, https://github.com/catalyst-cooperative/cheshire/issues
Author-email: Catalyst Cooperative <pudl@catalyst.coop>
License: MIT License
        
        Copyright (c) 2022 Catalyst Cooperative
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE.txt
Keywords: continuous delivery,continuous integration,github actions,linting,template,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.14
Requires-Dist: duckdb>=1.5.4
Requires-Dist: pandas[compression,excel,fss,gcp,parquet]>=3.0.3
Requires-Dist: pandera>=0.32.1
Requires-Dist: polars>=1.42.1
Requires-Dist: pyarrow>=25.0.0
Requires-Dist: pydantic[email]>=2.13.4
Provides-Extra: dev
Requires-Dist: build>=1.5.0; extra == 'dev'
Requires-Dist: prek>=0.4.10; extra == 'dev'
Requires-Dist: twine>=6.2.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocstrings-python>=2.0.5; extra == 'docs'
Requires-Dist: zensical>=0.0.50; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mdformat-mkdocs>=5; extra == 'lint'
Requires-Dist: ruff>=0.15.22; extra == 'lint'
Provides-Extra: tests
Requires-Dist: coverage>=7.15.2; extra == 'tests'
Requires-Dist: exceptiongroup>=1.3.1; extra == 'tests'
Requires-Dist: jupyter>=1.1.1; extra == 'tests'
Requires-Dist: nbconvert>=7.17.1; extra == 'tests'
Requires-Dist: nbformat>=5.10.4; extra == 'tests'
Requires-Dist: pytest-console-scripts>=1.4.1; extra == 'tests'
Requires-Dist: pytest-cov>=7.1.0; extra == 'tests'
Requires-Dist: pytest>=9.1.1; extra == 'tests'
Provides-Extra: types
Requires-Dist: pyrefly>=1.1.1; extra == 'types'
Description-Content-Type: text/markdown

# Cheshire: a Python Template Repository for Catalyst

<!-- readme-intro -->

[![pytest](https://github.com/catalyst-cooperative/cheshire/actions/workflows/pytest.yml/badge.svg)](https://github.com/catalyst-cooperative/cheshire/actions/workflows/pytest.yml)
[![docker-build-push](https://github.com/catalyst-cooperative/cheshire/actions/workflows/docker-build-push.yml/badge.svg)](https://github.com/catalyst-cooperative/cheshire/actions/workflows/docker-build-push.yml)
[![Codecov Test Coverage](https://img.shields.io/codecov/c/github/catalyst-cooperative/cheshire?style=flat&logo=codecov)](https://codecov.io/gh/catalyst-cooperative/cheshire)
[![Documentation](https://img.shields.io/github/deployments/catalyst-cooperative/cheshire/github-pages?style=flat&logo=githubpages&label=docs)](https://docs.catalyst.coop/cheshire)
[![PyPI Latest Version](https://img.shields.io/pypi/v/catalystcoop.cheshire?style=flat&logo=python)](https://pypi.org/project/catalystcoop.cheshire/)
[![conda-forge Version](https://img.shields.io/conda/vn/conda-forge/catalystcoop.cheshire?style=flat&logo=condaforge)](https://anaconda.org/conda-forge/catalystcoop.cheshire)
[![Supported Python Versions](https://img.shields.io/pypi/pyversions/catalystcoop.cheshire?style=flat&logo=python)](https://pypi.org/project/catalystcoop.cheshire/)

This template repository helps make new Python projects easier to set up and more
uniform. It contains a lot of infrastructure surrounding a minimal Python package named
`cheshire` (the cat who isn't entirely there...).

## Create a new repository from this template

- Choose a name for the new package that you are creating.
- The name of the repository should be the same as the name of the new Python package
    you are going to create. E.g. a repository at `catalyst-cooperative/cheshire` should
    be used to define a package named `cheshire`.
- Fork this template repository to create a new Python project repo.
    [See these instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
- Clone the new repository to your development machine.
- Install [pixi](https://pixi.sh) if you don't already have it.
- Run `pixi run prek install` in the newly cloned repository to install the
    [pre-commit hooks](https://pre-commit.com/) defined in `.pre-commit-config.yaml`,
    using [prek](https://prek.j178.dev/) as the runner.
- Run `pixi run test` from the top level of the repository to verify that everything
    is working correctly.

## Rename the package and distribution

Once you know that your forked version of the `cheshire` package is working as
expected, you should update the package and distribution names in your new repo to
reflect the name of your new package. The **package name** is determined by the name of
the directory under `src/` which contains the source code, and is the name you'll use
to import the package for use in a program, script, or notebook. E.g.:

```python
import cheshire
```

The **distribution name** is the name that is used to install the software using a
program like `pip`, `conda`, or `pixi`. It is often identical to the package name, but
can also contain a prefix namespace that indicates the individual or organization
responsible for maintaining the package. See
[PEP 423](https://peps.python.org/pep-0423/) for more on Python package naming
conventions. We are using the `catalystcoop` namespace for the packages that we
publish, so our `pudl` package becomes `catalystcoop.pudl` in the Python Package Index
(PyPI) or on `conda-forge`. Similarly the `cheshire` package becomes the
`catalystcoop.cheshire` distribution. The distribution name is determined by the
`project.name` defined in `pyproject.toml`.

```bash
pip install catalystcoop.cheshire
```

The package and distribution names are referenced in many of the files in the template
repository, and they all need to be replaced with the name of your new package. You can
use `grep -r` to search recursively through all of the files for the word `cheshire`
at the command line, or use the search-and-replace functionality of your IDE / text
editor. The name of the package directory under `src/` will also need to be changed.

- Supply any required tokens, e.g. for CodeCov.
- Rename the `src/cheshire` directory to reflect the new package name.
- Search for `cheshire` and replace it as appropriate everywhere. Sometimes this will
    be with a distribution name like `catalystcoop.cheshire` (the package as it appears
    for `pip` or `PyPI`) and sometimes this will be the importable package name (the name
    of the directory under `src` e.g. `cheshire`).
- Enable GitHub Pages for the new repository (Settings -> Pages -> Source: GitHub
    Actions) so the `docs` workflow can publish the documentation.

## What this template provides

See [the Tooling docs](https://docs.catalyst.coop/cheshire/tools/) for details on all
of the tooling this template sets up:

- [Python Package Skeleton](https://docs.catalyst.coop/cheshire/tools/#python-package-skeleton)
- [Environment & Task Management with Pixi](https://docs.catalyst.coop/cheshire/tools/#environment-task-management-with-pixi)
- [Devcontainer](https://docs.catalyst.coop/cheshire/tools/#devcontainer)
- [Pytest Testing Framework](https://docs.catalyst.coop/cheshire/tools/#pytest-testing-framework)
- [Git Pre-commit Hooks](https://docs.catalyst.coop/cheshire/tools/#git-pre-commit-hooks)
- [Code Formatting & Linting](https://docs.catalyst.coop/cheshire/tools/#code-formatting-linting)
- [Type Checking](https://docs.catalyst.coop/cheshire/tools/#type-checking)
- [Code & Documentation Linters](https://docs.catalyst.coop/cheshire/tools/#code-documentation-linters)
- [Test Coverage](https://docs.catalyst.coop/cheshire/tools/#test-coverage)
- [Documentation Builds](https://docs.catalyst.coop/cheshire/tools/#documentation-builds)
- [Documentation Publishing](https://docs.catalyst.coop/cheshire/tools/#documentation-publishing)
- [Dependabot](https://docs.catalyst.coop/cheshire/tools/#dependabot)
- [GitHub Actions](https://docs.catalyst.coop/cheshire/tools/#github-actions)

## About Catalyst Cooperative

[Catalyst Cooperative](https://catalyst.coop) is a small group of data wranglers and
policy wonks organized as a worker-owned cooperative consultancy. Our goal is a more
just, livable, and sustainable world. We integrate public data and perform custom
analyses to inform public policy
([Hire us!](https://catalyst.coop/hire-catalyst)). Our focus is primarily on
mitigating climate change and improving electric utility regulation in the United
States.

### Contact Us

- For general support, questions, or other conversations around the project that
    might be of interest to others, check out the
    [GitHub Discussions](https://github.com/catalyst-cooperative/pudl/discussions).
- If you'd like to get occasional updates about our projects
    [sign up for our email list](https://catalyst.coop/updates/).
- Want to schedule a time to chat with us one-on-one? Join us for
    [Office Hours](https://calend.ly/catalyst-cooperative/pudl-office-hours).
- More info on our website: <https://catalyst.coop>
- For private communication about the project or to hire us to provide customized data
    extraction and analysis, you can email the maintainers:
    [pudl@catalyst.coop](mailto:pudl@catalyst.coop).
