Developer guide¶
This page contains information about GEMSEO development and how to contribute to it. The source code of GEMSEO is available on gitlab, this is the place where code contributions shall be submitted. Note also that it is required to accompany any contribution with a Developer Certificate of Origin, certifying that the contribution is compatible with GEMSEO software licence.
We aim to have industrial quality standards for software, in order to:
- have a good and running software,
- be confident about it,
- facilitate collaborative work with the team,
- facilitate distribution to our partners.
To meet these goals, we use best practices described below, these practices are not optional, they are fully part of the development job.
Where the rules come from
The rules listed in this guide are shared by all the GEMSEO projects and by the coding agents of the team.
Their single source is the file common.md of the agents repository;
this page includes them and adds explanations.
To change a rule,
change common.md,
then update the revision of common.md that this page includes.
Quick start¶
First time setup:
- Clone the repository.
- Install the Requirements.
-
From the root of the git clone, create a development environment:
just install -
Run the checks:
just check -
Configure your IDE:
Environments¶
We use just for handling the development tasks, be it for coding, testing, documenting, checking, etc. This tool offers a simplified and high level interface to many ingredients used in development, while providing reproducible and isolated outcomes that are as much independent as possible of the platform and environment from which it is used.
All the recipes of just are defined in the file .justfile. The development environment is managed by uv and stored under .venv.
Requirements¶
Make sure Python 3 is installed, preferably 3.11.
First install uv or make sure your version is up-to-date, then install just with:
uv tool install rust-just
Finally, make sure that graphviz is installed (for rendering graphs).
How to use just¶
The recipes provided by just and their usage are described in the different sections below. In this section we give the common command line usages and tips.
List available recipes with:
just
Run a recipe named recipe with:
just recipe
The first invocation may take some time to proceed as uv sets up the environment; further invocations will be faster.
Activate the development environment with:
-
On Linux and MacOS:
source .venv/bin/activate -
On Windows:
.venv\Scripts\activate.bat
Activating the environment may be useful for instance to investigate a particular issue interactively.
Some recipes accept additional arguments, for example:
just recipe ARG1 --opt1
See the specific topics below for more information.
By default, recipes run with the Python version defined by the UV_PYTHON environment variable (defaulting to the version of the .python-version file, 3.11). To use a different version, set it before the recipe:
UV_PYTHON=3.13 just recipe
Coding¶
Coding environment¶
Create a development environment:
just install
This will create an environment under .venv with GEMSEO installed in editable mode. With an editable installation, GEMSEO appears installed in the development environment, but yet is still editable in the source tree.
Note
You do not need to activate this environment for coding into GEMSEO.
Coding style¶
We use the pep8 convention. The checking and formatting of the source code is done with ruff, which runs in the git hooks when creating a commit, or manually with just check.
- Run
just checkbefore committing; ruff's verdict is final, do not silence a rule with# noqawithout a reason. - All files must start with
from __future__ import annotations(enforced by ruff isort). - Code must run on the oldest Python version the project supports (3.11 for the gemseo family): no syntax or standard-library feature added later.
- Each import on its own line (
force-single-line = true). - License header is required on all source files; in the projects whose pre-commit config carries the hook, it is inserted automatically.
- Pydantic
BaseModelsubclasses and settings classes that are runtime-evaluated are listed in.ruff.tomlunder[lint.flake8-type-checking].runtime-evaluated-base-classes— add new ones there to avoidTCHerrors. - A function wrapped by
AutoPyDisciplinereturns variables, never expressions:AutoPyDisciplinetakes the output names from the names in thereturnstatement. Add# noqa: RET504to thatreturnline, since ruff would otherwise replace the assigned variable by its expression.
Warning
ruff moves imports solely used for typing annotations under a TYPE_CHECKING conditional block which is ignored at runtime.
In the case of pydantic models,
the typing annotations are necessary at runtime,
and an error is raised otherwise.
This is why the parent classes of the pydantic models are listed
in the runtime-evaluated-base-classes section of the .ruff.toml file.
Coding guidelines¶
Enumerations¶
- Use
enum.StrEnumfor constants whose values cross a string boundary (settings, CLI, JSON, a non-Python API); use a plainEnumotherwise. Enum member keys must be capital cased (e.g.RED,GAUSS_SEIDEL).
A StrEnum member is also a string,
so a user can pass either the member or its value,
and the value can travel through a REST API, a JSON file or a command line.
enum.StrEnum is part of the standard library since Python 3.11.
Error messages¶
Error messages will be read by humans, standing alone in a traceback or in a log record.
- Error messages are explicit, valid sentences that state the value received and what was expected. Assign the message to a variable before raising it (ruff
EM), chain withraise ... from err, and add context withadd_note()rather than a new exception type.
For instance:
try:
value = mapping[name]
except KeyError as error:
msg = f"The variable {name!r} does not exist; available ones are {sorted(mapping)}."
raise ValueError(msg) from error
Logging¶
- One
logger = logging.getLogger(__name__)per module, no per-call or per-instance loggers. The module logger is not a constant: write it in lower case, with noFinalannotation and no docstring. Pass the arguments to the logging call (logger.info("x = %s", x)) instead of formatting the message yourself (ruffG).
Naming the logger after the module makes the logger names track the package/module hierarchy, so it is intuitively obvious where events are logged just from the logger name. Passing the arguments to the logging call defers the formatting until the record is actually emitted.
Naming convention¶
- Method and function names must start with a verb (e.g.
compute_gradient,add_variable,get_size). Avoid noun-only names likegradientorsizefor callables; reserve those for attributes/properties. - Avoid
__call__; write a verb-named method (compute_<quantity>) and pass the bound method where a callable is expected.__call__is fine when a third-party API or a metaclass requires a callable object. - Package and module names are singular (e.g.
formulation,scenario,util,helper), not plural (formulations,scenarios,utils,helpers). Two exceptions:settings, as in asettings/subpackage or a<name>_settings.pymodule, and a module named after a class whose name is plural (e.g.lines.pyforLines). - Name a module after its class (
class_nameforClassName); you may strip a suffix shared by every module of the package (a_foo.AFoo→a) only when the package holds no unrelated module. Prefer explicit names for widely used APIs. A module with no class is namedutil, as a last resort when no name stating its purpose exists. - A module holds at most one public class, besides the small types that only serve it (an enum, a
NamedTuple, a dataclass, an exception). - A factory of
Thingis namedThingFactory, in the modulepath.thing.factory. - The name of an abstract class starts with
Base(e.g.BaseThing); a purely structural interface may be atyping.Protocolwith no prefix. - Constants and class attributes are named in lower snake case (e.g.
default_group,mdo_formulation_factory), annotated withFinalat module level orClassVaron a class, and followed by a docstring. This holds for protected names too (e.g._attr_not_to_serialize). Enum members are the only exception: they keep capital case. - A class, function, variable or
TypeVardefined at module level and used only in its own module is protected: its name starts with_(e.g._T). This holds in a protected module too (_foo.py), so that its public names are the ones other modules use. A name that other modules use may be protected too, when it must not be exposed to the users; prefer then a protected module or package holding public names (e.g.gemseo.core._process_flow), so that no module reads a protected name of another one. Uses in the tests do not count: a test may import a protected name. The exceptions are the names meant for the users even when no other module of the package uses them:- classes found by a factory;
- values passed to settings (enumerations, settings classes and their base classes);
- exceptions raised to the user;
- types of user callbacks or of returned objects;
- factory singletons;
- testing helpers for the plugins.
- A class attribute, instance attribute, method or property used only by its own class and its subclasses is protected. Its name starts with
_, not__, when a subclass uses it, since name mangling would hide it from the subclass. A member that another class or a function uses may be protected too, when it must not be exposed to the users (e.g.BaseDiscipline._has_jacobian): the caller then reads a protected member of another object, which is accepted. The exceptions are the members meant for the users even when nothing in the package uses them, and the members whose name is set from outside the class:- read accessors, even when only the tests use them;
- plotting and export methods;
- attributes described in the user guide or used in an example;
- the extension points that subclasses redefine;
- the members whose name is imposed by an external protocol (importlib, SciPy, ...).
- The two rules above apply to new names. Renaming an existing public name to a protected one is a breaking change: a changelog fragment must announce it.
Module naming is a trade-off:
shorter names make import statements more readable;
longer, more explicit names are easier to grep and clearer in error messages, logs and debugging sessions.
For instance,
in a package foo holding a_foo.AFoo, b_foo.BFoo and bar.Bar,
stripping the suffix yields a, b and bar,
and a reader could wrongly expect bar.BarFoo:
keep the suffixed forms.
String formatting¶
- Format strings with f-strings; use
str.format()only for a template defined before its values are known; never+or%, except in logging calls. Code must still parse on Python 3.11: no PEP 701 f-string syntax (reused quotes, backslashes or comments inside{}) and no t-strings.
See the documentation of the f-strings
and of str.format().
Git¶
Workflow¶
We use the gitflow for managing git branches. For the daily work, this basically means that evolutions of GEMSEO are done in feature branches created from the develop branch and merged back into it when finished.
- Branch from the up-to-date target branch (
developin the gemseo family). - For gemseo itself, push the branch to your fork, never to
gemseo/dev/gemseo; for the plugins and the other projects, push it to the project repository. - Keep a branch up to date by rebasing it on the target, never by merging the target
into it; push the rewritten branch with
--force-with-lease. - Rewrite freely your own feature branch (reorder, split, squash); never rewrite a
branch others build on (
develop,main, release branches).
The steps below apply these rules.
Initial setup¶
This setup only concerns GEMSEO: for the plugins and the other projects, clone the project repository and push your branches to it.
- Create your fork of the gemseo repository on gitlab.com.
- Clone your fork to your local machine:
git clone <url of your fork>
- Go to the directory of your fork.
- Add the reference upstream repository to you fork with:
git remote add upstream git@gitlab.com:gemseo/dev/gemseo.git
- Get access to the IRT CI by contacting a maintainer.
Working on a new feature¶
- Update your local copy of the upstream repository:
git fetch upstream
- Create a new feature branch on your local clone from the up to date upstream develop branch:
git checkout upstream/develop -b my_new_feature_branch
- Add commits to your feature branch.
- On a regular basis (ideally everyday), keep your feature branch up to date with the upstream evolution of the develop branch so to make the future merge into develop easier:
git fetch upstream
git rebase upstream/develop
- Push your current local feature branch to your fork at least once a day; after a rebase, the push must rewrite the branch of your fork:
git push --force-with-lease origin HEAD
- Once pushed, the gitlab CI will run the tests on your branch, you will receive an email notification in case of failure.
Finishing a feature¶
- When your feature branch is ready to be merged in the upstream develop branch, your branch shall become a merge request (MR).
- The title of the MR is a valid commit subject (see Commit message): GitLab squashes the commits of the MR by default and uses this title as the commit message.
- If applicable, add a changelog fragment that will be later inserted into the changelog (see Changelog). To do so, create one or more files named after the issue number and kind of change (added, breaking, changed, deprecated, fixed or removed), for instance
123.fixed.md, inchangelog/fragments. With no issue, prefix the name with+, for instance+boxplot-options.changed.md. - MR basic information.
- How to create a MR.
- Assign the MR to a maintainer (AntoineD by default) which will handle the choice of the reviewers (discussed during the scrum meeting).
- Set the milestone.
- Set the issue relating or closing the MR, if any.
- If for some reasons the branch of the MR requires more work, the MR may be set to Draft.
- If a review discussion goes beyond the scope of a branch, one or several review threads of a MR may be turned into a new issue to be resolved in a future branch.
- If a review thread has not been resolved by a new commit to the reviewed branch and shall not be dealt with in a new issue, it shall be marked as resolved by the reviewer.
- If changes have been pushed to the branch of a MR, the reviewers shall be notified.
-
When all the MR discussion threads are resolved:
- The reviewers shall approve the MR,
- The MR creator shall ask the branch to be merged.
Reviewing a MR¶
- You can choose how the changes of the MR branch are displayed.
- You may leave reviews or comments on one or more lines.
- You may make code suggestions that could be committed as is the reviewed branch.
- Once done, you shall submit your review.
- You shall check that your review comments have been addressed, if so you shall mark them as resolved.
- When all the reviews have been resolved, you shall approve the MR.
Git hooks¶
When a commit is being created, git will perform predefined actions:
- remove the trailing whitespaces,
- fix the end of files,
- check toml, yaml and json files are well formed,
- check that no big file is committed,
- check bad symbolic links,
- check or fix some of the python docstrings formatting,
- fix the Python import order,
- fix the Python code formatting,
- check for Python coding issues (see Coding style),
- fix some of the above coding issues.
- fix outdated Python syntax,
- check the commit message (see Commit message),
- check for forbidden
printusage, - check for misused
loggingformatting, - check for
.mdfiles issues. - check or fix license headers,
- check for docstrings formatting,
- check for docstrings coverage,
Those actions will eventually modify the files about to be committed. In this case your commit is denied and you have to check that the modifications are OK, then add the modifications to the commit staged files before creating the commit again.
Do not bypass the hooks with git commit --no-verify.
Commit message¶
We use conventional commits for writing clear and useful git commit messages. The commit message should be structured as follows:
<type>(optional scope): <description>
[optional body]
[optional footer(s)]
- Commit messages follow Conventional Commits; the Python projects enforce that with a
Commitizen pre-commit hook. Write
<type>(<scope>): <description>. - The type is one of
feat,fix,docs,style,refactor,perf,test,build,ci,choreandrevert. - The scope is the subpackage touched (e.g.
optimization,space); omit it when the change spans the project. - The description is imperative, in lower case, with no final dot; the whole subject fits within 72 characters.
- The body explains why the change is made, compared with the previous behaviour.
- A breaking change has
!after the type or scope and aBREAKING CHANGE:footer. - A footer
Closes #123names the issue the change resolves. - A merge request title is a valid commit subject in the format above: GitLab squashes by default and uses it as the commit message.
The types mean:
feat: a new feature,fix: a bug fix,docs: documentation only changes,style: changes that do not affect the meaning of the code,refactor: a code change that neither fixes a bug nor adds a feature,perf: a code change that improves performance,test: adding missing tests or correcting existing tests,build: changes that affect the build system or external dependencies,ci: changes to the CI configuration files and scripts,chore: other changes that do not modify the source code or the tests,revert: the revert of a previous commit.
You may use commitizen to easily create commits that follow conventional commits. Install it with:
uv tool install commitizen
Run it and and let it drive you through with:
cz commit
Commit message examples:
feat(study): open browser when generating XDSM
fix(scenario): xdsm put back filename arg
Commit best practices¶
The purpose of these best practices is to ease the code reviews, commit reverting (rollback changes) bisecting (find regressions), branch merging or rebasing.
- One idea per commit, with its tests. Do not rename and change a file in the same commit, so git keeps track of the rename; do not mix formatting and behaviour changes.
- Every commit keeps the tests passing, so
git bisectworks. Run the tests covering the change before pushing; CI runs the rest. - Never bypass the hooks (
--no-verify); fix what they report.
The history of a branch stays linear when it is rebased on its target instead of merging the target into it (see Workflow). git can help to achieve this, and remember how you resolved a conflict so that the next rebase reuses it:
git config pull.rebase true
git config rerere.enabled true
Testing¶
Testing is mandatory in any engineering activity, which is based on trial and error. All developments shall be tested:
- this gives confidence to the code,
- this enables code refactoring with mastered consequences: tests must pass!
Tests writing guidelines¶
We use pytest for writing and executing all the GEMSEO tests. Older tests were written with the unittest module from the Python standard library but newer tests shall be written with pytest.
Logic¶
- Write new tests with pytest functions and fixtures, not
unittest.TestCase. - Arrange / Act / Assert / Cleanup, one behaviour per test so it has one reason to
fail. Variants of one behaviour are
pytest.mark.parametrizecases withids=naming the condition. Extend an existing test of the behaviour rather than adding a new one. - Tests share no state and pass alone and in any order: the suites run in parallel under pytest-xdist.
- Do not create loggers in tests; check logs with
caplog, oncaplog.record_tuplesor the messages, not with a substring ofcaplog.text. - Check a warning with
pytest.warns. - Skip a test on Windows with
@pytest.mark.skip_under_windows.
The Arrange, Act, Assert, Cleanup steps split the testing code into its setup, the call under test, its checks and the teardown.
A test with one behaviour has one reason to fail,
so its name and its failure tell what broke.
The information provided to the user by the error and logging messages shall be correct,
which is why the tests check them;
let pytest manage the logging and use its builtin features,
whose settings are defined in .pytest.ini.
Fixtures¶
These live in the gemseo package, so any project that depends on gemseo can use them. Enable the shared fixtures by importing them in the project's tests/conftest.py:
from gemseo.util.testing.pytest_conftest import * # noqa: F401,F403
Fixtures:
tmp_wd/module_tmp_wd: temporary working directoriesreset_factory: clearsBaseFactorysingleton cache between tests (use when testing factories)snapshot_allclose: factory returning asnapshotthat compares Python-level floats withinrtol/atol, for snapshots whose last bits drift across OS or Python versionenable_function_statistics,enable_discipline_status,enable_discipline_statistics: flip the matchingconfigurationflag for the duration of the testrestore_configuration_options: restores the boolean options of the globalconfigurationafter the test (theenable_*fixtures above build on it); use it in a test that changes these options itselfskip_under_windows: autouse, backs theskip_under_windowsmarker
Validation of error messages¶
The helper assert_exception in src/gemseo/util/testing/helper.py replaces pytest.raises(Exc, match=...) with a snapshot of the full exception message,
captured via syrupy.
Why it exists¶
match=regexes are brittle, require heavy escaping, and only check a partial match.- Snapshots capture the full message verbatim, and differences are visible when the snapshot is updated.
- The helper normalizes the message before comparing it,
so that a snapshot holds across platforms and versions:
it rewrites
errors.pydantic.dev/<ver>/v/...toerrors.pydantic.dev/X.Y/v/..., the OS part of aFileNotFoundErrormessage to[Errno 2] No such file or directory, and the memory addresses to0xMEM.
Signature¶
@contextlib.contextmanager
def assert_exception(
exception: type[BaseException] | tuple[type[BaseException], ...],
snapshot: SnapshotAssertion,
) -> Generator[pytest.ExceptionInfo, None, None]
It yields the ExceptionInfo so you can run additional assertions on attributes, chained exceptions, etc.
Usage¶
from gemseo.util.testing.helper import assert_exception
def test_thing(snapshot):
with assert_exception(ValueError, snapshot):
do_thing()
Multiple exception types:
with assert_exception((ValueError, TypeError), snapshot):
...
Extra checks on the caught exception:
with assert_exception(MyError, snapshot) as exception_info:
...
assert exception_info.value.code == 42
Migrating from match=¶
Drop the match=... argument, add the snapshot fixture parameter to the test, and switch the context manager. Then regenerate the snapshots:
uv run pytest --snapshot-update tests/path/to/test_file.py
Review the resulting __snapshots__/*.ambr diff and commit the .ambr files alongside the test changes.
Gotchas¶
- Never combine
--snapshot-updatewithxdist(-n). Parallel workers race on the same.ambrfile and produce corrupted or partial output. Drop-nwhen updating snapshots. - Unused snapshot entries fail the session even when every test passes.
- Other non-deterministic content in messages (temporary paths, timestamps) will break snapshots.
Either stabilize the source, or add a normalization to
assert_exceptioninhelper.py.
Validation of figures¶
- Snapshot matplotlib figures with the
snapshot_matplotlibfixture of syrupy-matplotlib (auto mode, no assertion to write). When a figure differs under another matplotlib version, neither raise the tolerance nor re-baseline: record a pinned variant with--snapshot-update --snapshot-matplotlib-pin-variantand commit__snapshots_variants__/. - Snapshot a plotly figure with
assert fig.to_json() == snapshot.
Matplotlib¶
For figures generated by matplotlib,
use the snapshot_matplotlib fixture provided by the syrupy-matplotlib plugin.
The fixture runs in auto assertion mode:
figures created during the test are compared against baseline images automatically,
no explicit assertion is needed.
Baseline images are stored under tests/**/__snapshots__/<module>/.
Add the snapshot_matplotlib fixture to your test:
def test_my_plot(snapshot_matplotlib):
my_function_creating_a_matplotlib_figure()
Read the documentation of syrupy-matplotlib for more examples.
On the first run, or whenever a plot intentionally changes, generate or refresh the snapshots with:
just test --snapshot-update
Commit the resulting snapshot files alongside the test.
When a figure renders differently under another matplotlib version, do not loosen the tolerance and do not re-baseline, as that would break the other environment. Since syrupy-matplotlib 0.3.0, record an extra baseline pinned to the matplotlib version at hand with:
just test --snapshot-update --snapshot-matplotlib-pin-variant
Commit the resulting __snapshots_variants__/ files as well.
See Baseline variants for the semantics and the caveats.
Plotly¶
For Plotly figures,
use syrupy for snapshot testing.
A snapshot serializes the figure's data structure into an test_{suffix}.ambr file under a __snapshots__ directory in the same directory as test_{suffix}.py;
future runs diff the live output against it and fail on any change.
Add the snapshot fixture to your test:
def test_my_plot(snapshot):
fig = my_function_returning_a_plotly_figure()
assert fig.to_json() == snapshot
On the first run, or whenever a plot intentionally changes, generate or refresh the snapshots with:
just test --snapshot-update
Commit the resulting .ambr files alongside the test.
Validation of arrays and generated files¶
- Compare arrays with
numpy.testing(assert_allclosewith explicit tolerances,assert_array_equal), neverassert np.allclose(...); compare scalars withpytest.approx. - A test never writes in the source tree: pass a path under
tmp_path, or usetmp_wdwhen the code writes to the current directory.
The NumPy testing tools report where two arrays differ,
whereas assert np.allclose(...) only reports that the assertion failed.
Writing the files of a test in a temporary directory keeps the root directory clean
and lets the tests run in parallel.
Executing tests¶
Run the tests with:
just test
You can pass options to pytest directly, for instance:
just test --last-failed --step-wise
To speed up the execution of the tests, you may execute exclusively or skip some of them by using the following pytest marks: - post: tests that post processing compare images - slow: tests that are slow - integration: integration tests
For instance, skip all the post with
just test -m 'not post'
Tests coverage¶
- Every changed line and branch is covered: check with
just coverage-diff <target>, which fails under 100 %.
Get the coverage information of the whole suite with:
just coverage
and check the coverage of the lines changed by your branch with:
just coverage-diff upstream/develop
See pytest-cov and diff-cover for more information.
Documentation¶
The documentation of the develop branch is available online: develop documentation.
Generating the documentation¶
The documentation is built with Zensical. Generate the documentation with:
just doc
Writing guidelines¶
Documenting classes, functions, methods, attributes, modules, etc... is mandatory. End users and developers shall not have to guess the purpose of an API and how to use it.
Style¶
The documentation is written in Markdown. For more information, please refer to this introduction to Markdown and these advanced features.
Use the Google Style Docstrings format for documenting the code. This example module shows how to write such docstrings.
- Google docstring convention (
[lint.pydocstyle] convention = "google"). - Docstrings use the Markdown format, not reStructuredText: write a cross-reference as
[ClassName][module.ClassName]. - Write a protected name, or a name whose module path has a protected part (
_foo.py,_pkg/), as inline code, not as a cross-reference: the API reference renders neither, so the link would be broken. This holds in the documentation pages and the examples too, where such a link fails the strict documentation build. The exception is a name that a public package re-exports: link to its public path (e.g.[h][pkg.h]forpkg._foo.h). Write the short name when the name is defined in the same module (e.g.`_dump_yaml`; for a member,`_member`in its own class and`Class._member`elsewhere in the module), and the full path otherwise (e.g.`gemseo.util._tracer._yaml.dump_yaml_to_file`). When the name or its module path becomes public, turn these mentions into cross-references. - Every function/method docstring must include an
Args:section when it has parameters (excludingself/cls), and aReturns:section when it returns a non-Nonevalue. Applies to private (_name,__name) and@staticmethodcallables too. - Every public module, class, function, method and attribute has a docstring; document an attribute with a string literal right after its assignment, not with a
#:comment (griffe drops it). The gemseo docstring style is shown by the example moduleexample_google_docstrings.pyof gemseo-org (docs/contribute/templates/). - An overriding method that keeps the meaning of the parent method inherits its docstring through
docstring-inheritance: write no docstring and add# noqa: D102to itsdefline.
Type hints¶
The type hints are used when generating the functions and methods documentation, they will also be used gradually to check and improved the code quality with the help of a type checker like mypy. See this example module for a typical example.
- Annotate parameters with the abstract types of
collections.abc(Iterable,Sequence,Mapping) and returns with the exact type returned; annotate*argsand**kwargswith the value type only. Put typing-only imports underTYPE_CHECKING. - Return
typing.Selffrom a method that returns its own instance, rather than a boundTypeVar. - On Python 3.11, declare a type alias with
TypeAliasand a generic withTypeVarandGeneric, not with thetypestatement orclass Foo[T](PEP 695).
Accepting abstract types lets a caller pass any suitable container,
while returning the exact type tells the caller everything it can do with the result.
Importing a name under TYPE_CHECKING also breaks the circular imports that the type hints may cause:
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from gemseo.core.discipline import Discipline
Line feeds and citations¶
- In the documentation pages and the docstrings of the gemseo projects, use semantic line feeds: one sentence per line, split at natural breaks between clauses.
- Cite a reference with
[@key], the key being an entry ofdocs/references.bib; a key missing from the bibliography fails the documentation build.
With semantic line feeds, a text file becomes far easier to edit and version control. You can have a look at the current page's source for instance.
Examples¶
There are two types of examples in the documentation:
- tutorials: they are used to teach a concept; they can be seen as mini-lessons;
- how-to guides: they are used to answer a specific question; they are intended for users who have mastered the basics.
Use templates for writing tutorials (template_tutorial.py) and how-to guides (template_how_to.py).
Check that the examples run correctly with:
just test -m doc_examples
Versioning¶
We use semantic versioning for defining the version numbers of GEMSEO.
- Versions follow semantic versioning (MAJOR.MINOR.PATCH): a change that breaks the public API needs a new MAJOR version, a backward-compatible feature a new MINOR version, and a backward-compatible fix a new PATCH version.
Changelog¶
- A user-visible change comes with its changelog entry in the same merge request, in the project's format.
- Changelog entries describe what changed for users between releases, not what changed inside a branch. Write the net effect relative to the last release.
- User-visible changes only: public API, documented behavior, settings, CLI,
dependencies, deprecations. Nothing about private names (
_foo), internal helpers, tests, CI, tooling, or docs infrastructure — if a user cannot observe it, it does not belong in the changelog. - Do not add an entry for something introduced and then modified or removed within the same unreleased cycle; amend or delete the original entry instead.
- No branch-internal churn: refactors, intermediate fixes to unreleased code, review follow-ups, or "fixed the fix" entries.
In GEMSEO, the changelog entries are fragments, see Finishing a feature.
Benchmarking¶
Use pyperf to create valid benchmark, mind properly tuning the system for the benchmark (see the docs).
Profiling¶
The Python standard library provides a profiler, mind using it with controlled system like for benchmarking. The profiling data could be analyzed with one of these tools:
- snakeviz
- kcachegrind, after having converted the profiling data with pyprof2calltree
Configure PyCharm¶
PyCharm is one of the best tools for writing Python code. We provide some configuration files to help configuring it for developing the GEMSEO projects.
Code style¶
Configure PyCharm to match the code style used by the GEMSEO projects. Download this file, open the PyCharm settings, go to Editor > Code Style > Python and select Import Scheme...:

Check and format¶
Some tools used by the git hooks can be executed in order to be notified of code issues earlier and avoid having to fix files when creating a commit.
Install the Ruff plugin by opening the PyCharm settings, and searching in Plugins > Marketplace. Then, activate all the options and provide the path to the ruff executable that shall be in the following directory relative to the root of the git clone of the project:
- On Linux and MacOS:
.venv/bin/ruff. - On Windows:
.venv\Scripts\ruff.exe.
Configure VSCode¶
vscode could serve as an alternative to PyCharm. To configure it for developing GEMSEO, we offer the base settings.json and extensions.json, which need to be placed within the local .vscode directory.
Download Configuration Files¶
settings.json: This file primarily contains Python rules for code style, formatting, debugging, testing, and indexing. You can download it.extensions.json: This file provides useful extension recommendations when browsing the Marketplace. You can download it.
Configuration¶
Place both downloaded files in the .vscode directory of your project.
Modify settings.json according to your preferences. You can adjust the settings either globally (User parameters) or per project (Workspace parameters).
Extensions¶
Ensure you install all recommended extensions mentioned in extensions.json. These extensions enhance the functionality and productivity of vscode for Python development.