From 30751e75ec6a0455f3ae337b64aa63503f9445fe Mon Sep 17 00:00:00 2001 From: Graham Hukill Date: Thu, 5 Mar 2026 11:50:42 -0500 Subject: [PATCH 1/2] gitignore jetbrains IDE --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index cfa926f..67dda4f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ _site _build + +.idea/ \ No newline at end of file From 8b842b4313c2827b0603a7c33b7fb4978ad075df Mon Sep 17 00:00:00 2001 From: Graham Hukill Date: Tue, 24 Mar 2026 11:50:07 -0400 Subject: [PATCH 2/2] Update python guidelines Why these changes are being introduced: The python guidelines were remarkably accurate given a fairly lengthy stay between updates, but some areas were beginning to need some updates. Additionally, we are currently actively experimenting with a "specification" of sorts for python projects, a document that is designed to be a bit more granular than these guidelines. How this addresses that need: * Updates sections where small changes are needed (e.g. pipenv -> uv) * Adds new "python projects specification" section that briefly notes and links to a specification document with more granular details about project conventions Side effects of this change: * First experimental integration of the dev docs wiki and the new python project specification repository Relevant ticket(s): * https://mitlibraries.atlassian.net/browse/IN-1697 --- languages/python.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/languages/python.md b/languages/python.md index 5fba04c..9c55b77 100644 --- a/languages/python.md +++ b/languages/python.md @@ -17,11 +17,17 @@ Note: it's important that you follow all of the setup instructions in the templa If you notice anything that needs to be updated in either of the templates, please submit a PR! +## Python Project Specification + +The [Python Project Specification](https://github.com/MITLibraries/spec-python-projects) is a declarative standard for CLI and Lambda Python projects. It defines the exact tooling, configuration, file structure, and workflow targets that a compliant project should have. + +Where this page provides general principles and recommendations, the specification aims to provide auditable, concrete requirements, e.g. `pyproject.toml` configuration, Makefile targets, pre-commit hooks, CI workflows, Dockerfile patterns, etc. + ## Style and coding Conventions In general, you should follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) and [PEP 257](https://www.python.org/dev/peps/pep-0257/). Unless otherwise stated here, assume those two guidelines are in effect. -If you are providing function docstrings, use [reST](http://docutils.sourceforge.net/rst.html). In addition to a description of what a function does, you should document the parameters: +If you are providing function docstrings, use [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings). In addition to a description of what a function does, you should document the parameters: ```python def widgetize(widget): @@ -30,7 +36,8 @@ def widgetize(widget): This ensures that the widget conforms to the strict standards governing conformant widgets. - :param widget: a widget what needs widgetizing + Args: + widget: A widget what needs widgetizing. """ standardize(widget) @@ -40,25 +47,17 @@ def widgetize(widget): Our standard Python code checkers in all repositories include: -- [bandit](https://bandit.readthedocs.io/en/latest/) - security -- [black](https://black.readthedocs.io/en/stable/) - formatting -- [isort](https://pycqa.github.io/isort/) - import order -- [mypy](https://mypy.readthedocs.io/en/stable/) - type hinting -- [pylama](https://github.com/klen/pylama) - formatting and code quality (wrapper around several other tools) +- [ruff](https://docs.astral.sh/ruff/) - formatting and linting (replaces black, isort, pylama, and bandit) +- [mypy](https://mypy.readthedocs.io/en/stable/) - type checking +- [pip-audit](https://pypi.org/project/pip-audit/) - dependency security auditing These tools should be used during development and are run automatically in Github Actions during CI. They are all included in the template repositories listed above, and have integrations for common code editors to allow automatic checking and reformatting during development. -The linters are usually run together with the `make lint` command in a project's Makefile. See the template repositories for examples. +The linters are usually run together with the `make lint` command in a project's Makefile, which runs `ruff check`, `ruff format`, and `mypy`. See the template repositories for examples. ## Dependencies -Use [Pipenv](https://pipenv.readthedocs.io/en/latest/) to manage dependencies for Python applications. If there's some reason you need to support pip, then you should still manage dependencies with pipenv, but generate your `requirements.txt` file as needed with: - -``` -pipenv requirements > requirements.txt -``` - -If you are creating a Python library, [Poetry](https://python-poetry.org/) is the preferred package and distribution manager. +Use [uv](https://docs.astral.sh/uv/) to manage dependencies for Python applications. Dependencies should be declared in `pyproject.toml` and locked with `uv lock`. ## Project Documentation