Python¶

Note

This guide is under development and is likely to change.

python version:: 3.12
last-updated:: Apr 24, 2025

The team uses the following files to configure, setup and install our python packages. This guide assumes a repo created with the Templates project or using the sqr-bot jr create a repo functionality.

pyproject.toml¶

[build-system]
requires = ["setuptools>=64", "setuptools-scm>=8"]
build-backend = "setuptools.build_meta"

[project]
name = "ts-{name}"
description = "{name} is a Commandable SAL Component for the `Vera C. Rubin Observatory <https://lsst.org>`_."
license = { text = "GPL" }
classifiers = [ "Programming Language :: Python :: 3" ]
dependencies = ["pymodbus"]
readme = "README.rst"
urls = { documentation = "https://ts-{name}.lsst.io", source_code = "https://github.com/lsst-ts/ts_{name}"}
dynamic = ["version"]

[tool.setuptools.dynamic]
version = { attr = "setuptools_scm.get_version" }

[tool.setuptools.packages.find]
where = [ "python" ]

[project.scripts]
run_{name} = "lsst.ts.{name}:run_{name}"

[tool.setuptools_scm]


[tool.pytest.ini_options]
asyncio_mode = "auto"

[project.optional-dependencies]
dev = ["documenteer[pipelines]"]

Note

The tool.setuptools_scm section is mandatory and needs to be empty.

setup.py¶

import setuptools

import setuptools_scm

setuptools.setup(
    version=setuptools_scm.get_version(
        write_to="python/lsst/ts/${CSC}/version.py"
    )
)

Note

Replace ${CSC} with the CSC pyton module name, e.g. watcher or ess/csc.

__init__.py¶

try:
    from .version import __version__
except ImportError:
    __version__ = "?"

Style Guide¶

The team uses the following tools to enforce the style guide.

black:: An opinionated autoformatter.
isort:: An opinionated import sorter.
flake8:: A style checker with many different plugins to enforce different rules.
check-yaml:: Checks yaml files for proper format.
check-xml:: Checks xml files for proper format.
mypy:: Performs type checking on the code (optional).

There are several other optional style guide tools as well. This is enforced by a tool called pre-commit.

Version History¶

In the past a version_history.rst or similar file was maintained manually for each project by each sofware developer. For projects where multiple developers are involved this often led to either merge conflicts, version conflicts or both. TSSW therefore aims to migrate all projects to towncrier which should be added as a pre-commit hook. After adding the towncrier pre-commit hook, copy the following README.rst file into the doc/news directory.

README.rst¶

Recording Changes
=================

This directory contains "news fragments" which are small, structured text files that contain information about changes or updates that will be included in the release notes.
These fragments are used to automatically generate changelogs or release notes.
They can be written restructured text format or plain text.

Each file should be named like ``<JIRA TICKET>.<TYPE>.<EXT>`` with a file extension defining the markup format (``rst|md``).
The ``<TYPE>`` should be one of:

* ``feature``: A new feature
* ``bugfix``: A bug fix.
* ``perf``: A performance enhancement.
* ``doc``: A documentation improvement.
* ``removal``: A deprecation or removal of API.
* ``misc``: Other minor changes and/or additions

An example file name would therefore look like ``DM-40534.doc.rst``.

Each developer now has to create the news fragments for the changes they have made on their own branches, instead of adding them to the release notes directly.
The news fragments are then automatically integrated into the release notes by the ``towncrier`` tool.

You can test how the content will be integrated into the release notes by running ``towncrier build --draft --version=v<X.XX.X>``.
Note that you have to run it from the root repository directory (i.e. ``watcher``).

In order to update the release notes file for real, the person responsible for the release should run:

.. code-block:: bash

   $ towncrier build --version=v<X.XX.X>


.. note::

   When running towncrier to build the changelog, you may be prompted to confirm the deletion of fragments.
   If you would like to retain the fragments in the doc/news directory do not confirm the deletion.

Note also that ``towncrier`` can be installed from PyPI or conda-forge.

After that you can add news fragments following the format instructions in the README.rst file. News fragments can be added manually using any text editor or IDE. It is also possible to create a news fragment using the towncrier command in a shell. The command to create a news fragment is

The fragment types are explained in the README.rst file. The command will take care of adding and increment numbering of the files if multiple news fragments of the same type are added for the same ticket.

Note

Using towncrier from the command line requires the towncrier conda package to be installed.

Once all code changes for a new version have been made, the version history file can be updated using towncrier as follows:

Merge all branches that contribute to the new version into develop.

Merge develop into main.
Issue the following towncrier command:
towncrier build --version=vX.Y.Z
See Versioning for a description of the versioning scheme used by TSSW.
Commit the changes to main using a descriptive commit message like Update the version history..

Tag that commit using the same version as used in the `towncrier build` command.

Push the changes to GitHub.

Open a PR on main and request a review.

Once the PR has been approved, merge main into develop.

Note

Some projects are configured to automatically delete the HEAD branch when a PR is merged. This means that the main branch is deleted when main is merged into develop. In that case simply restore the main branch and all is well.

Note

The first time that a PR for main is opened, it will contain all commits from develop. Subsequent PRs will only have the latest commits.