cogeol¶

Features¶

cogeol is a library which allows you to:

Manage Python versions in your projects: no more checking if a given Python version reached its end of life, cogeol will do it for you.
Align with Scientific Python SPEC0 ⧉: cogeol will allow you to align your project to the three latest supported Python versions
Caching: cogeol reaches out to End of Life Date ⧉ to check the latest supported Python versions, and caches the results on disk to avoid unnecessary network requests.
Based on cog ⧉: Manage versions of Python by statically generated code (see examples below!)

Quick start¶

Installation¶

> pip install cogeol

Usage¶

Tip

Check out the documentation ⧉ for all available functionalities and public-facing API.

Open pyproject.toml of your project and find necessary to have requires-python field.
Update it as follows (comments are crucial!):

# [[[cog
# import cog
# import cogeol
#
# cycle = cogeol.scientific()[-1]["cycle"]
# cog.out(f'requires-python = ">={cycle}"')
# ]]]
requires-python = ">=3.9"
# [[[end]]]

Now run the following from the command line:

> cog -c -r pyproject.toml

Now your requires-python field will be updated to the latest supported Python version!

For example (Python 3.11 is the latest supported version at the time of writing):

# [[[cog
# import cog
# import cogeol
#
# cycle = cogeol.scientific()[-1]["cycle"]
# cog.out(f'requires-python = ">={cycle}"')
# ]]]
requires-python = ">=3.11"
# [[[end]]] (sum: uZEo+p96oZ)

Note

Please notice a checksum, which verifies consistency of the changes at each run

Examples¶

Specifying Python version classifiers (click me)

You can automate the classifiers in your `pyproject.toml` file like this:

# [[[cog
# import cog
# import cogeol
#
# for version in reversed(cogeol.scientific()):
#     cycle = version["cycle"]
#     cog.outl(f'  "Programming Language :: Python :: {cycle}",')
# ]]]
"Programming Language :: Python :: 3.11",
# [[[end]]]

Now run the following from the command line:

> cog -c -r pyproject.toml

and you should see the following (__notice all versions are present!__):

# [[[cog
# import cog
# import cogeol
#
# for version in reversed(cogeol.scientific()):
#     cycle = version["cycle"]
#     cog.outl(f'  "Programming Language :: Python :: {cycle}",')
# ]]]
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
# [[[end]]] (sum: FeG7grp2Dw)

Caching (click me)

Let's assume you have the following code snippet in `github-workflow.yml`:

...
jobs:
  tests-reusable:
    strategy:
      matrix:
        python:
          #
          #           DO NOT EDIT UNTIL end marker
          #
          # [[[cog
          # import cog
          # import cogeol
          #
          # for version in reversed(cogeol.scientific()):
          #     cycle = version['cycle']
          #     cog.outl(f'          - "{cycle}"')
          # ]]]
          - "3.11"
          # [[[end]]] (sum: l3d2zGv79j)

in addition to your code in `pyproject.toml` using `cogeol`. Now, if you run:

> cog -c -r pyproject.toml github-workflow.yml

The following will happen: - Both files will be updated with appropriate Python versions - __Only one call to [End of Life Date](https://endoflife.date) will be made__ (the results are cached on disk) Next time you run the same command, the results will be read from the cache

Advanced (click me)

For more examples check out this project's: - `pyproject.toml` file (see [here](https://github.com/open-nudge/cogeol/blob/main/pyproject.toml)) - Tests of the last three versions in GitHub Actions workflow (see [here](https://github.com/open-nudge/cogeol/blob/main/.github/workflows/tests-reusable.yml))