catalystcoop.cheshire


Namecatalystcoop.cheshire JSON
Version 0.4.1 PyPI version JSON
download
home_page
SummaryReplace this text with a one line description of the package.
upload_time2023-09-17 21:10:32
maintainer
docs_urlNone
author
requires_python<3.12,>=3.10
licenseMIT 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.
keywords template testing linting github actions continuous integration continuous delivery
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage 
            Cheshire: a Python Template Repository for Catalyst
=======================================================================================

.. readme-intro

.. image:: https://github.com/catalyst-cooperative/cheshire/workflows/tox-pytest/badge.svg
   :target: https://github.com/catalyst-cooperative/cheshire/actions?query=workflow%3Atox-pytest
   :alt: Tox-PyTest Status

.. image:: https://github.com/catalyst-cooperative/cheshire/workflows/docker-build-push/badge.svg
   :target: https://github.com/catalyst-cooperative/cheshire/actions?query=workflow%3Adocker-build-push
   :alt: Docker build status

.. image:: https://img.shields.io/codecov/c/github/catalyst-cooperative/cheshire?style=flat&logo=codecov
   :target: https://codecov.io/gh/catalyst-cooperative/cheshire
   :alt: Codecov Test Coverage

.. image:: https://img.shields.io/readthedocs/catalystcoop-cheshire?style=flat&logo=readthedocs
   :target: https://catalystcoop-cheshire.readthedocs.io/en/latest/
   :alt: Read the Docs Build Status

.. image:: https://img.shields.io/pypi/v/catalystcoop.cheshire?style=flat&logo=python
   :target: https://pypi.org/project/catalystcoop.cheshire/
   :alt: PyPI Latest Version

.. image:: https://img.shields.io/conda/vn/conda-forge/catalystcoop.cheshire?style=flat&logo=condaforge
   :target: https://anaconda.org/conda-forge/catalystcoop.cheshire
   :alt: conda-forge Version

.. image:: https://img.shields.io/pypi/pyversions/catalystcoop.cheshire?style=flat&logo=python
   :target: https://pypi.org/project/catalystcoop.cheshire/
   :alt: Supported Python Versions

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black>
   :alt: Any color you want, so long as it's black.

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.
* Run ``pre-commit install`` in the newly clone repository to install the
  `pre-commit hooks <https://pre-commit.com/>`__ defined in ``.pre-commit-config.yaml``
* Create the ``cheshire`` conda environment by running ``conda env create`` or
  (preferably) ``mamba env create`` in the top level of the repository.
* Activate the new conda environment with ``conda activate cheshire``.
* Run ``tox`` 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.:

.. code:: python

  import cheshire

The **distribution name** is the name that is used to install the software using a
program like  ``pip``, ``conda``, or ``mamba``. 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 pacakge. See :pep:`423`
`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``

.. code:: 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``)
* Create the new project / package at Read The Docs.

What this template provides
=======================================================================================

Python Package Skeleton
-----------------------
* The ``src`` directory contains the code that will be packaged and deployed on the user
  system. That code is in a directory with the same name as the package.
* Using a separate ``src`` directory helps avoid accidentally importing the package when
  you're working in the top level directory of the repository.
* A simple python module (``dummy.py``), and a separate module providing a command line
  interface to that module (``cli.py``) are included as examples.
* Any files in the ``src/package_data/`` directory will also be packaged and deployed.
* What files are included in or excluded from the package on the user's system is
  controlled by the ``MANIFEST.in`` file and some options in the call to ``setup()`` in
  ``setup.py``.
* The CLI is deployed using ``project.scripts`` defined in ``pyproject.toml``.
* We use ``setuptools_scm`` to obtain the package's version directly from ``git`` tags,
  rather than storing it in the repository and manually updating it.
* ``README.rst`` is read in and used for the pacakge's ``long_description``. This is
  what is displayed on the PyPI page for the package.
* By default we create at least three sets of "extras" -- additional optional package
  dependencies that can be installed in special circumstances: ``dev``, ``docs```, and
  ``tests``. The packages listed there are used in development, building the docs, and
  running the tests (respectively) but aren't required for a normal user who is just
  installing the package from ``pip`` or ``conda``. These are defined under the
  ``project.optional-dependencies`` section of ``pyproject.toml``
* Python has recently evolved a more diverse community of build and packaging tools.
  Which flavor is being used by a given package is indicated by the contents of
  ``pyproject.toml``. That file also contains configuration for a few other tools,
  including ``black`` and ``ruff``.

Pytest Testing Framework
------------------------
* A skeleton `pytest <https://docs.pytest.org/>`_ testing setup is included in the
  ``tests/`` directory.
* Tests are split into ``unit`` and ``integration`` categories.
* Session-wide test fixtures, additional command line options, and other pytest
  configuration can be added to ``tests/conftest.py``
* Exactly what pytest commands are run during continuous integration controlled by Tox.
* Pytest can also be run manually without using Tox, but will use whatever your
  personal python environment happens to be, rather than the one specified by the
  package. Running pytest on its own is a good way to debug new or failing tests
  quickly, but we should always use Tox and its virtual environment for actual testing.

Test Coordination with Tox
--------------------------
* We define several different test environments for use with Tox in ``tox.ini``
* `Tox <https://tox.wiki/en/latest/>`__ is used to run pytest in an isolated Python
  virtual environment.
* We also use Tox to coordinate running the code linters, building the documentation,
  and releasing the software to PyPI.
* The default Tox environment is named ``ci`` and it will run the linters, build the
  documentation, run all the tests, and generate test coverage statistics.

Git Pre-commit Hooks
--------------------
* A variety of sanity checks are defined as git pre-commit hooks -- they run any time
  you try to make a commit, to catch common issues before they are saved. Many of these
  hooks are taken from the excellent `pre-commit project <https://pre-commit.com/>`__.
* The hooks are configured in ``.pre-commit-config.yaml``
* For them to run automatically when you try to make a commit, you **must** install the
  pre-commit hooks in your cloned repository first. This only has to be done once.
* These checks are run as part of our CI, and the CI will fail if the pre-commit hooks
  fail.
* We also use the `pre-commit.ci <https://pre-commit.ci>`__ service to run the same
  checks on any code that is pushed to GitHub, and to apply standard code formatting
  to the PR in case it hasn't been run locally prior to being committed.

Code Formatting & Linting
-------------------------
To avoid the tedium of meticulously formatting all the code ourselves, and to ensure as
standard style of formatting and sytactical idioms across the codebase, we use the
``black`` and ``ruff`` code formatters, which run as pre-commit hooks. These can be
integrated directly into your text editor or IDE with the appropriate plugins. The
formatters are included in ``.pre-commit-config.yaml``. The ``ruff`` linter / formatter
has a huge array of configuration options and different kinds of checks it can run,
which are defined under the ``tool.ruff`` section of ``pyproject.toml``.

We also have a custom hook that clears Jupyter notebook outputs prior to committing.

Code & Documentation Linters
----------------------------
To catch errors before commits are made, and to ensure uniform formatting across the
codebase, we also use linters outside of ``ruff``. They don't change the code or
documentation files, but they will raise an error or warning when something doesn't
look right so you can fix it.

* `doc8 <https://github.com/pycqa/doc8>`__
* `mypy <https://mypy.readthedocs.io/en/stable/index.html>`__ Does static type checking,
  and ensures that our code uses type annotations.
* `pre-commit <https://pre-commit.com>`__ has a collection of built-in checks that `use
  pygrep to search Python files <https://github.com/pre-commit/pygrep-hooks>`__ for
  common problems like blanket ``# noqa`` annotations, as well as `language agnostic
  problems <https://github.com/pre-commit/pre-commit-hooks>`__ like accidentally
  checking large binary files into the repository or having unresolved merge conflicts.
* `hadolint <https://github.com/AleksaC/hadolint-py>`__ checks Dockerfiles for errors
  and violations of best practices. It runs as a pre-commit hook.

Test Coverage
-------------
* We use Tox and a the pytest `coverage <https://coverage.readthedocs.io/en/latest/>`__
  plugin to measure and record what percentage of our codebase is being tested, and to
  identify which modules, functions, and individual lines of code are not being
  exercised by the tests.
* When you run ``tox`` or ``tox -e ci`` (which is equivalent) a summary of the test
  coverage will be printed at the end of the tests (assuming they succeed). The full
  details of the test coverage is written to ``coverage.xml``.
* There are some configuration options for this process set in the ``.coveragerc`` file
  in the top level directory of the repository.
* When the tests are run via the ``tox-pytest`` workflow in GitHub Actions, the test
  coverage data from the ``coverage.xml`` output is uploaded to a service called
  `CodeCov <https://about.codecov.io/>`__ that saves historical data about our test
  coverage, and provides a nice visual representation of the data -- identifying which
  subpackages, modules, and individual lines of are being tested. For example, here are
  the results
  `for the cheshire repo <https://app.codecov.io/gh/catalyst-cooperative/cheshire>`__.
* The connection to CodeCov is configured in the ``.codecov.yml`` YAML file.
* In theory, we should be able to automatically turn CodeCov on for all of our GitHub
  repos, and it just Just Work, but in practice we've had to turn it on in the GitHub
  configuration one-by-one. Open source repositories are also supposed to be able to
  upload to the CodeCov site without requiring authentication, but this also hasn't
  worked, so thus far we've needed to request a new token for each repository. This
  token is stored in ``.codecov.yml``.
* Once it's enabled, CodeCov also adds a couple of test coverage checks to any pull
  request, to alert us if a PR reduces overall test coverage (which we would like to
  avoid).

Documentation Builds
--------------------
* We build our documentation using `Sphinx <https://www.sphinx-doc.org/en/master/>`__.
* Standalone docs files are stored under the ``docs/`` directory, and the Sphinx
  configuration is there in ``conf.py`` as well.
* We use `Sphinx AutoAPI <https://sphinx-autoapi.readthedocs.io/en/latest/>`__ to
  convert the docstrings embedded in the python modules under ``src/`` into additional
  documentation automatically.
* The top level documentation index simply includes this ``README.rst``, the
  ``LICENSE.txt`` and ``CODE_OF_CONDUCT.md`` files are similarly referenced. The only
  standalone documentation file under ``docs/`` right now is the ``release_notes.rst``.
* Unless you're debugging something specific, the docs should always be built using
  ``tox -e docs`` as that will lint the source files using ``doc8`` and ``rstcheck``,
  and wipe previously generated documentation to build everything from scratch. The docs
  are also rebuilt as part of the normal Tox run (equivalent to ``tox -e ci``).
* If you add something to the documentation generation process that needs to be cleaned
  up after, it should be integrated with the Sphinx hooks. There are some examples of
  how to do this at the bottom of ``docs/conf.py`` in the "custom build operations"
  section. For example, this is how we automatically regenerate the data dictionaries
  based on the PUDL metadata whenever the docs are built, ensuring that the docs stay up
  to date.

Documentation Publishing
------------------------
* We use the popular `Read the Docs <https://readthedocs.io>`__ service to host our
  documentation.
* When you open a PR, push to ``dev`` or ``main``, or tag a release, the associated
  documentation is automatically built on Read the Docs.
* There's some minimal configuration stored in the ``.readthedocs.yml`` file, but
  setting up this integration for a new repository requires some setup on the Read the
  Docs site.
* Create an account on Read the Docs using your GitHub identity, go to "My Projects"
  under the dropdown menu in the upper righthand corner, and click on "Import a
  Project." It should list the repositories that you have access to on GitHub. You may
  need to click on the Catalyst Cooperative logo in the right hand sidebar.
* It will ask you for a project name -- this will become part of the domain name for the
  documentation page on RTD and should be the same as the distribution name, but with
  dots and underscores replaced with dashes. E.g. ``catalystcoop-cheshire`` or
  ``catalystcoop-pudl-catalog``.
* Under Advanced Settings, make sure you
  `enable builds on PRs <https://docs.readthedocs.io/en/stable/pull-requests.html>`__.
  This will add a check ensuring that the documentation has built successfully on RTD
  for any PR in the repo.
* Under the Builds section for the new project (repo) you'll need to tell it which
  branches you want it to build, beyond the default ``main`` branch.
* Once the repository is connected to Read the Docs, an initial build of the
  documentation from the ``main`` branch should start.

Dependabot
----------
We use GitHub's `Dependabot <https://docs.github.com/en/code-security/dependabot/dependabot-version-updates>`__
to automatically update the allowable versions of packages we depend on. This applies
to both the Python dependencies specified in ``setup.py`` and to the versions of the
`GitHub Actions <https://docs.github.com/en/actions>`__ that we employ. The dependabot
behavior is configured in ``.github/dependabot.yml``

GitHub Actions
--------------
Under ``.github/workflows`` are YAML files that configure the `GitHub Actions
<https://docs.github.com/en/actions>`__ associated with the repository. We use GitHub
Actions to:

* Run continuous integration using `tox <https://tox.wiki>`__ on several different
  versions of Python.
* Build a Docker container directly and push it to Docker Hub using the
  `docker-build-push action <https://github.com/docker/build-push-action>`__.
* Release a new version of the package on PyPI when a version tag is pushed.
* Automatically merge bot PRs from pre-commit.ci and the dependabot.

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>`__
* Follow us on Twitter: `@CatalystCoop <https://twitter.com/CatalystCoop>`__
* 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>`__

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "catalystcoop.cheshire",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "<3.12,>=3.10",
    "maintainer_email": "",
    "keywords": "template,testing,linting,github actions,continuous integration,continuous delivery",
    "author": "",
    "author_email": "Catalyst Cooperative <pudl@catalyst.coop>",
    "download_url": "https://files.pythonhosted.org/packages/3f/e5/c0d9bb1ecc1a538c3cb8193552bf2f0bb571df0da4eb16b30bf8226af3a8/catalystcoop.cheshire-0.4.1.tar.gz",
    "platform": null,
    "description": "Cheshire: a Python Template Repository for Catalyst\n=======================================================================================\n\n.. readme-intro\n\n.. image:: https://github.com/catalyst-cooperative/cheshire/workflows/tox-pytest/badge.svg\n   :target: https://github.com/catalyst-cooperative/cheshire/actions?query=workflow%3Atox-pytest\n   :alt: Tox-PyTest Status\n\n.. image:: https://github.com/catalyst-cooperative/cheshire/workflows/docker-build-push/badge.svg\n   :target: https://github.com/catalyst-cooperative/cheshire/actions?query=workflow%3Adocker-build-push\n   :alt: Docker build status\n\n.. image:: https://img.shields.io/codecov/c/github/catalyst-cooperative/cheshire?style=flat&logo=codecov\n   :target: https://codecov.io/gh/catalyst-cooperative/cheshire\n   :alt: Codecov Test Coverage\n\n.. image:: https://img.shields.io/readthedocs/catalystcoop-cheshire?style=flat&logo=readthedocs\n   :target: https://catalystcoop-cheshire.readthedocs.io/en/latest/\n   :alt: Read the Docs Build Status\n\n.. image:: https://img.shields.io/pypi/v/catalystcoop.cheshire?style=flat&logo=python\n   :target: https://pypi.org/project/catalystcoop.cheshire/\n   :alt: PyPI Latest Version\n\n.. image:: https://img.shields.io/conda/vn/conda-forge/catalystcoop.cheshire?style=flat&logo=condaforge\n   :target: https://anaconda.org/conda-forge/catalystcoop.cheshire\n   :alt: conda-forge Version\n\n.. image:: https://img.shields.io/pypi/pyversions/catalystcoop.cheshire?style=flat&logo=python\n   :target: https://pypi.org/project/catalystcoop.cheshire/\n   :alt: Supported Python Versions\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n   :target: https://github.com/psf/black>\n   :alt: Any color you want, so long as it's black.\n\nThis template repository helps make new Python projects easier to set up and more\nuniform. It contains a lot of infrastructure surrounding a minimal Python package named\n``cheshire`` (the cat who isn't entirely there...).\n\nCreate a new repository from this template\n=======================================================================================\n\n* Choose a name for the new package that you are creating.\n* The name of the repository should be the same as the name of the new Python package\n  you are going to create. E.g. a repository at ``catalyst-cooperative/cheshire`` should\n  be used to define a package named ``cheshire``.\n* Fork this template repository to create a new Python project repo.\n  `See these instructions <https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template>`__.\n* Clone the new repository to your development machine.\n* Run ``pre-commit install`` in the newly clone repository to install the\n  `pre-commit hooks <https://pre-commit.com/>`__ defined in ``.pre-commit-config.yaml``\n* Create the ``cheshire`` conda environment by running ``conda env create`` or\n  (preferably) ``mamba env create`` in the top level of the repository.\n* Activate the new conda environment with ``conda activate cheshire``.\n* Run ``tox`` from the top level of the repository to verify that everything is working\n  correctly.\n\nRename the package and distribution\n=======================================================================================\n\nOnce you know that your forked version of the ``cheshire`` package is working as\nexpected, you should update the package and distribution names in your new repo to\nreflect the name of your new package. The **package name** is determined by the name of\nthe directory under ``src/`` which contains the source code, and is the name you'll use\nto import the package for use in a program, script, or notebook. E.g.:\n\n.. code:: python\n\n  import cheshire\n\nThe **distribution name** is the name that is used to install the software using a\nprogram like  ``pip``, ``conda``, or ``mamba``. It is often identical to the package\nname, but can also contain a prefix namespace that indicates the individual or\norganization responsible for maintaining the pacakge. See :pep:`423`\n`PEP 423 <https://peps.python.org/pep-0423/>`__ for more on Python package naming\nconventions. We are using the ``catalystcoop`` namespace for the packages that we\npublish, so our ``pudl`` package becomes ``catalystcoop.pudl`` in the\nPython Package Index (PyPI) or on ``conda-forge``. Similarly the ``cheshire`` package\nbecomes the ``catalystcoop.cheshire`` distribution. The distribution name is determined\nby the ``project.name`` defined in ``pyproject.toml``\n\n.. code:: bash\n\n  pip install catalystcoop.cheshire\n\nThe package and distribution names are referenced in many of the files in the template\nrepository, and they all need to be replaced with the name of your new package. You can\nuse ``grep -r`` to search recursively through all of the files for the word ``cheshire``\nat the command line, or use the search-and-replace functionality of your IDE / text\neditor. The name of the package directory under ``src/`` will also need to be changed.\n\n* Supply any required tokens, e.g. for CodeCov\n* Rename the ``src/cheshire`` directory to reflect the new package name.\n* Search for ``cheshire`` and replace it as appropriate everywhere. Sometimes\n  this will be with a distribution name like ``catalystcoop.cheshire``\n  (the package as it appears for ``pip`` or ``PyPI``) and sometimes this will be the\n  importable package name (the name of the directory under ``src`` e.g. ``cheshire``)\n* Create the new project / package at Read The Docs.\n\nWhat this template provides\n=======================================================================================\n\nPython Package Skeleton\n-----------------------\n* The ``src`` directory contains the code that will be packaged and deployed on the user\n  system. That code is in a directory with the same name as the package.\n* Using a separate ``src`` directory helps avoid accidentally importing the package when\n  you're working in the top level directory of the repository.\n* A simple python module (``dummy.py``), and a separate module providing a command line\n  interface to that module (``cli.py``) are included as examples.\n* Any files in the ``src/package_data/`` directory will also be packaged and deployed.\n* What files are included in or excluded from the package on the user's system is\n  controlled by the ``MANIFEST.in`` file and some options in the call to ``setup()`` in\n  ``setup.py``.\n* The CLI is deployed using ``project.scripts`` defined in ``pyproject.toml``.\n* We use ``setuptools_scm`` to obtain the package's version directly from ``git`` tags,\n  rather than storing it in the repository and manually updating it.\n* ``README.rst`` is read in and used for the pacakge's ``long_description``. This is\n  what is displayed on the PyPI page for the package.\n* By default we create at least three sets of \"extras\" -- additional optional package\n  dependencies that can be installed in special circumstances: ``dev``, ``docs```, and\n  ``tests``. The packages listed there are used in development, building the docs, and\n  running the tests (respectively) but aren't required for a normal user who is just\n  installing the package from ``pip`` or ``conda``. These are defined under the\n  ``project.optional-dependencies`` section of ``pyproject.toml``\n* Python has recently evolved a more diverse community of build and packaging tools.\n  Which flavor is being used by a given package is indicated by the contents of\n  ``pyproject.toml``. That file also contains configuration for a few other tools,\n  including ``black`` and ``ruff``.\n\nPytest Testing Framework\n------------------------\n* A skeleton `pytest <https://docs.pytest.org/>`_ testing setup is included in the\n  ``tests/`` directory.\n* Tests are split into ``unit`` and ``integration`` categories.\n* Session-wide test fixtures, additional command line options, and other pytest\n  configuration can be added to ``tests/conftest.py``\n* Exactly what pytest commands are run during continuous integration controlled by Tox.\n* Pytest can also be run manually without using Tox, but will use whatever your\n  personal python environment happens to be, rather than the one specified by the\n  package. Running pytest on its own is a good way to debug new or failing tests\n  quickly, but we should always use Tox and its virtual environment for actual testing.\n\nTest Coordination with Tox\n--------------------------\n* We define several different test environments for use with Tox in ``tox.ini``\n* `Tox <https://tox.wiki/en/latest/>`__ is used to run pytest in an isolated Python\n  virtual environment.\n* We also use Tox to coordinate running the code linters, building the documentation,\n  and releasing the software to PyPI.\n* The default Tox environment is named ``ci`` and it will run the linters, build the\n  documentation, run all the tests, and generate test coverage statistics.\n\nGit Pre-commit Hooks\n--------------------\n* A variety of sanity checks are defined as git pre-commit hooks -- they run any time\n  you try to make a commit, to catch common issues before they are saved. Many of these\n  hooks are taken from the excellent `pre-commit project <https://pre-commit.com/>`__.\n* The hooks are configured in ``.pre-commit-config.yaml``\n* For them to run automatically when you try to make a commit, you **must** install the\n  pre-commit hooks in your cloned repository first. This only has to be done once.\n* These checks are run as part of our CI, and the CI will fail if the pre-commit hooks\n  fail.\n* We also use the `pre-commit.ci <https://pre-commit.ci>`__ service to run the same\n  checks on any code that is pushed to GitHub, and to apply standard code formatting\n  to the PR in case it hasn't been run locally prior to being committed.\n\nCode Formatting & Linting\n-------------------------\nTo avoid the tedium of meticulously formatting all the code ourselves, and to ensure as\nstandard style of formatting and sytactical idioms across the codebase, we use the\n``black`` and ``ruff`` code formatters, which run as pre-commit hooks. These can be\nintegrated directly into your text editor or IDE with the appropriate plugins. The\nformatters are included in ``.pre-commit-config.yaml``. The ``ruff`` linter / formatter\nhas a huge array of configuration options and different kinds of checks it can run,\nwhich are defined under the ``tool.ruff`` section of ``pyproject.toml``.\n\nWe also have a custom hook that clears Jupyter notebook outputs prior to committing.\n\nCode & Documentation Linters\n----------------------------\nTo catch errors before commits are made, and to ensure uniform formatting across the\ncodebase, we also use linters outside of ``ruff``. They don't change the code or\ndocumentation files, but they will raise an error or warning when something doesn't\nlook right so you can fix it.\n\n* `doc8 <https://github.com/pycqa/doc8>`__\n* `mypy <https://mypy.readthedocs.io/en/stable/index.html>`__ Does static type checking,\n  and ensures that our code uses type annotations.\n* `pre-commit <https://pre-commit.com>`__ has a collection of built-in checks that `use\n  pygrep to search Python files <https://github.com/pre-commit/pygrep-hooks>`__ for\n  common problems like blanket ``# noqa`` annotations, as well as `language agnostic\n  problems <https://github.com/pre-commit/pre-commit-hooks>`__ like accidentally\n  checking large binary files into the repository or having unresolved merge conflicts.\n* `hadolint <https://github.com/AleksaC/hadolint-py>`__ checks Dockerfiles for errors\n  and violations of best practices. It runs as a pre-commit hook.\n\nTest Coverage\n-------------\n* We use Tox and a the pytest `coverage <https://coverage.readthedocs.io/en/latest/>`__\n  plugin to measure and record what percentage of our codebase is being tested, and to\n  identify which modules, functions, and individual lines of code are not being\n  exercised by the tests.\n* When you run ``tox`` or ``tox -e ci`` (which is equivalent) a summary of the test\n  coverage will be printed at the end of the tests (assuming they succeed). The full\n  details of the test coverage is written to ``coverage.xml``.\n* There are some configuration options for this process set in the ``.coveragerc`` file\n  in the top level directory of the repository.\n* When the tests are run via the ``tox-pytest`` workflow in GitHub Actions, the test\n  coverage data from the ``coverage.xml`` output is uploaded to a service called\n  `CodeCov <https://about.codecov.io/>`__ that saves historical data about our test\n  coverage, and provides a nice visual representation of the data -- identifying which\n  subpackages, modules, and individual lines of are being tested. For example, here are\n  the results\n  `for the cheshire repo <https://app.codecov.io/gh/catalyst-cooperative/cheshire>`__.\n* The connection to CodeCov is configured in the ``.codecov.yml`` YAML file.\n* In theory, we should be able to automatically turn CodeCov on for all of our GitHub\n  repos, and it just Just Work, but in practice we've had to turn it on in the GitHub\n  configuration one-by-one. Open source repositories are also supposed to be able to\n  upload to the CodeCov site without requiring authentication, but this also hasn't\n  worked, so thus far we've needed to request a new token for each repository. This\n  token is stored in ``.codecov.yml``.\n* Once it's enabled, CodeCov also adds a couple of test coverage checks to any pull\n  request, to alert us if a PR reduces overall test coverage (which we would like to\n  avoid).\n\nDocumentation Builds\n--------------------\n* We build our documentation using `Sphinx <https://www.sphinx-doc.org/en/master/>`__.\n* Standalone docs files are stored under the ``docs/`` directory, and the Sphinx\n  configuration is there in ``conf.py`` as well.\n* We use `Sphinx AutoAPI <https://sphinx-autoapi.readthedocs.io/en/latest/>`__ to\n  convert the docstrings embedded in the python modules under ``src/`` into additional\n  documentation automatically.\n* The top level documentation index simply includes this ``README.rst``, the\n  ``LICENSE.txt`` and ``CODE_OF_CONDUCT.md`` files are similarly referenced. The only\n  standalone documentation file under ``docs/`` right now is the ``release_notes.rst``.\n* Unless you're debugging something specific, the docs should always be built using\n  ``tox -e docs`` as that will lint the source files using ``doc8`` and ``rstcheck``,\n  and wipe previously generated documentation to build everything from scratch. The docs\n  are also rebuilt as part of the normal Tox run (equivalent to ``tox -e ci``).\n* If you add something to the documentation generation process that needs to be cleaned\n  up after, it should be integrated with the Sphinx hooks. There are some examples of\n  how to do this at the bottom of ``docs/conf.py`` in the \"custom build operations\"\n  section. For example, this is how we automatically regenerate the data dictionaries\n  based on the PUDL metadata whenever the docs are built, ensuring that the docs stay up\n  to date.\n\nDocumentation Publishing\n------------------------\n* We use the popular `Read the Docs <https://readthedocs.io>`__ service to host our\n  documentation.\n* When you open a PR, push to ``dev`` or ``main``, or tag a release, the associated\n  documentation is automatically built on Read the Docs.\n* There's some minimal configuration stored in the ``.readthedocs.yml`` file, but\n  setting up this integration for a new repository requires some setup on the Read the\n  Docs site.\n* Create an account on Read the Docs using your GitHub identity, go to \"My Projects\"\n  under the dropdown menu in the upper righthand corner, and click on \"Import a\n  Project.\" It should list the repositories that you have access to on GitHub. You may\n  need to click on the Catalyst Cooperative logo in the right hand sidebar.\n* It will ask you for a project name -- this will become part of the domain name for the\n  documentation page on RTD and should be the same as the distribution name, but with\n  dots and underscores replaced with dashes. E.g. ``catalystcoop-cheshire`` or\n  ``catalystcoop-pudl-catalog``.\n* Under Advanced Settings, make sure you\n  `enable builds on PRs <https://docs.readthedocs.io/en/stable/pull-requests.html>`__.\n  This will add a check ensuring that the documentation has built successfully on RTD\n  for any PR in the repo.\n* Under the Builds section for the new project (repo) you'll need to tell it which\n  branches you want it to build, beyond the default ``main`` branch.\n* Once the repository is connected to Read the Docs, an initial build of the\n  documentation from the ``main`` branch should start.\n\nDependabot\n----------\nWe use GitHub's `Dependabot <https://docs.github.com/en/code-security/dependabot/dependabot-version-updates>`__\nto automatically update the allowable versions of packages we depend on. This applies\nto both the Python dependencies specified in ``setup.py`` and to the versions of the\n`GitHub Actions <https://docs.github.com/en/actions>`__ that we employ. The dependabot\nbehavior is configured in ``.github/dependabot.yml``\n\nGitHub Actions\n--------------\nUnder ``.github/workflows`` are YAML files that configure the `GitHub Actions\n<https://docs.github.com/en/actions>`__ associated with the repository. We use GitHub\nActions to:\n\n* Run continuous integration using `tox <https://tox.wiki>`__ on several different\n  versions of Python.\n* Build a Docker container directly and push it to Docker Hub using the\n  `docker-build-push action <https://github.com/docker/build-push-action>`__.\n* Release a new version of the package on PyPI when a version tag is pushed.\n* Automatically merge bot PRs from pre-commit.ci and the dependabot.\n\nAbout Catalyst Cooperative\n=======================================================================================\n`Catalyst Cooperative <https://catalyst.coop>`__ is a small group of data\nwranglers and policy wonks organized as a worker-owned cooperative consultancy.\nOur goal is a more just, livable, and sustainable world. We integrate public\ndata and perform custom analyses to inform public policy (`Hire us!\n<https://catalyst.coop/hire-catalyst>`__). Our focus is primarily on mitigating\nclimate change and improving electric utility regulation in the United States.\n\nContact Us\n----------\n* For general support, questions, or other conversations around the project\n  that might be of interest to others, check out the\n  `GitHub Discussions <https://github.com/catalyst-cooperative/pudl/discussions>`__\n* If you'd like to get occasional updates about our projects\n  `sign up for our email list <https://catalyst.coop/updates/>`__.\n* Want to schedule a time to chat with us one-on-one? Join us for\n  `Office Hours <https://calend.ly/catalyst-cooperative/pudl-office-hours>`__\n* Follow us on Twitter: `@CatalystCoop <https://twitter.com/CatalystCoop>`__\n* More info on our website: https://catalyst.coop\n* For private communication about the project or to hire us to provide customized data\n  extraction and analysis, you can email the maintainers:\n  `pudl@catalyst.coop <mailto:pudl@catalyst.coop>`__\n",
    "bugtrack_url": null,
    "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. ",
    "summary": "Replace this text with a one line description of the package.",
    "version": "0.4.1",
    "project_urls": {
        "Documentation": "https://catalystcoop-cheshire.readthedocs.io",
        "Issue Tracker": "https://github.com/catalyst-cooperative/cheshire/issues",
        "Source": "https://github.com/catalyst-cooperative/cheshire"
    },
    "split_keywords": [
        "template",
        "testing",
        "linting",
        "github actions",
        "continuous integration",
        "continuous delivery"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1e374d73e6c89b27b69707de3ccde5868555bbe153b486926dde500e93a50c52",
                "md5": "8445a54afd4d749c95eb2376999353c8",
                "sha256": "e485c6abba33835f6c50e4435a07b671480c6494008c03cb4e0ff26e34f7245e"
            },
            "downloads": -1,
            "filename": "catalystcoop.cheshire-0.4.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8445a54afd4d749c95eb2376999353c8",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.12,>=3.10",
            "size": 12672,
            "upload_time": "2023-09-17T21:10:31",
            "upload_time_iso_8601": "2023-09-17T21:10:31.088100Z",
            "url": "https://files.pythonhosted.org/packages/1e/37/4d73e6c89b27b69707de3ccde5868555bbe153b486926dde500e93a50c52/catalystcoop.cheshire-0.4.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "3fe5c0d9bb1ecc1a538c3cb8193552bf2f0bb571df0da4eb16b30bf8226af3a8",
                "md5": "af1f3fc7d8296053211fe65b0b54afa2",
                "sha256": "4b31af30f582dc01653e4aa811977c76ec8468b7678bb0ba062600e095c4d6df"
            },
            "downloads": -1,
            "filename": "catalystcoop.cheshire-0.4.1.tar.gz",
            "has_sig": false,
            "md5_digest": "af1f3fc7d8296053211fe65b0b54afa2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.12,>=3.10",
            "size": 24305,
            "upload_time": "2023-09-17T21:10:32",
            "upload_time_iso_8601": "2023-09-17T21:10:32.282710Z",
            "url": "https://files.pythonhosted.org/packages/3f/e5/c0d9bb1ecc1a538c3cb8193552bf2f0bb571df0da4eb16b30bf8226af3a8/catalystcoop.cheshire-0.4.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-09-17 21:10:32",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "catalyst-cooperative",
    "github_project": "cheshire",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "tox": true,
    "lcname": "catalystcoop.cheshire"
}
Elapsed time: 2.91090s