> built 2026-10-13 11:17 UTC from 3a3895f (master) · isee 0.2.82. Details: build_info.json # index.html.md # Introduction Python continuous integration (CI) support tools. To install: `pip install isee` [Documentation here](https://i2mint.github.io/isee/index.html). 1. [Introduction]() 2. [Goal]() 3. [Workflow]() 4. [Results and Logs]() 5. [Versioning]() 6. [Skip CI]() 7. [Hosting]() 8. [How to setup CI]() * [For a GitHub repository]() 9. [Running CI Locally]() 10. [Useful resources]() 11. [Troubleshooting]() * [Common non fatal error during publishing]() * [Github token problems (e.g. tagging)]() * [Version tag misalignment]() # Goal The goal of CI is to automate code formatting, validation, deployment and publishing of packages. # Workflow A CI pipeline is triggered when new code is pushed to a remote repository. Every CI pipeline does at least: 1. Code formatting * Apply automated linting on source code * Push back the formatted code to the remote repository 2. Code validation * Testing (unit tests, integration tests, doctests) * Docstring validation (only for frameworks) 3. Deployment to an integration environment for applications / Publishing for frameworks – (only on *master* and only if the *Validation* step succeeded) * Semi-automated versioning (see the [Versioning]() section) + Tag the repository with the new generated version number * Packaging * Deployment / Publishing # Results and Logs You can see your CI pipeline’s result and logs: * From your **GitLab project page → CI/CD → Pipelines** * From your **GitHub project page → Actions → Continuous Integration** # Versioning Versioning is semi-automatically resolved: if you want the major or minor part to be bumped, you only have to add ***[bump major]*** or ***[bump minor]*** to your commit message on *master* (versioning is not applied to other branches). Example, the current version number is **1.0.5**. If you commit with the following message: ```default Added some new stuff. ``` the new version number will be **1.0.6**. But if you commit with the following message: ```default Added some great new stuff! [bump minor] ``` the new version number will be **1.1.0**. Finally, if you commit with the following message: ```default Added some extraordinary new stuff!!! [bump major] ``` the new version number will be **2.0.0**. # Skip CI You can prevent the CI pipeline from being triggered by adding ***[skip ci]*** to your commit message. Example: ```default Updated the README file. [skip ci] ``` **Be careful!** If you skip the CI process, any new code will not be validated and no new version will be deployed/published. So, think twice before using it. # Hosting CI pipelines for GitHub public repositories are run on GitHub-hosted runners. See the [GitHub documentation](https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/introduction-to-github-actions#runners) for more details # How to setup CI This “How to” section applies to python package projects only. If you want to setup CI to an application project or another programing language, you will have to modify the CI pipeline definition according to your needs. ## For a GitHub repository 1. Add this [ci.yml]() file to the `github/workflow/` directory (create the directory if it doesn’t exist) into your local repository. Note that [wads](https://pypi.org/project/wads/) does it for you by running the following command from the project’s root directory (documentation [here](https://i2mint.github.io/wads/module_docs/wads/populate.html)): ```default populate . --root-url=GITHUB_ROOT_URL ``` Note that you can specify the root directory (in case you’re not in the root directory), root url (in case the directory is not already associated to a git repo), and have many other parametrization choices. Fear not: `populate` will **not** create or modify the `ci.yml` file (or any other file) if there is one already. 1. In the `ci.yml` file, replace `#PROJECT_NAME#` with the project name (must be the exact same name as the main module of the project, not needed if you ran the `populate` tool because it did it for you) and modify the pipeline workflow to suit the project’s needs. Documentation [here](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions). 2. Add secrets `PYPI_USERNAME` and `PYPI_PASSWORD` with your PYPI credentials to the remote repository. Documentation [here](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets). 3. If you want the project’s documentation to be published, configure the project’s Github Pages for the project by selecting the `/docs` folder. Documentation [here](https://guides.github.com/features/pages/). 4. Push your code and see the execution of the new `Continuous Integration` workflow. Documentation [here](https://docs.github.com/en/free-pro-team@latest/actions/managing-workflow-runs). Consider using [wads](https://pypi.org/project/wads/) to automatically validate your code locally, commit and push by running the following command (documentation [here](https://i2mint.github.io/wads/module_docs/wads/pack.html)): ```default pack check-in 'Your commit message.' ``` # Running CI Locally You can run your GitHub Actions CI workflow locally before pushing, using [`act`](https://github.com/nektos/act). This helps catch issues early and saves CI minutes. ## Quick Start ```bash # Check if dependencies are installed python -m isee.local_cli --check-deps # Run your entire CI workflow locally python -m isee.local_cli # Run a specific job (e.g., validation) python -m isee.local_cli -j validation # Dry run to see what would execute python -m isee.local_cli --dry-run ``` ## Prerequisites Install `act` and ensure Docker is running: **macOS:** ```bash brew install act ``` **Linux:** ```bash curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash ``` ## Common Options ```bash # Run with specific Python version python -m isee.local_cli -j validation -m python-version:3.10 # Use custom workflow file python -m isee.local_cli -w .github/workflows/test.yml # Quiet mode (less output) python -m isee.local_cli -q ``` For detailed documentation, see [LOCAL_CLI_USAGE.md](https://github.com/i2mint/isee/blob/master/LOCAL_CLI_USAGE.md). # Useful resources [troubleshooting tests](https://github.com/i2mint/tested/wiki/Troubleshooting-Tests) # Troubleshooting ## Common (non fatal) error during publishing It has been reported that users get this error: ```default /home/runner/work/_temp/1a136567-cb0c-4c9f-a44f-4cbe6633d4eb.sh: line 2: --non-interactive: command not found Error: Process completed with exit code 127. ``` when publishing. The package publishes fine, but this error causes the CI “publish” part to show up as red, which is annoying. Solution: This will happen when any of the variables (most of the time, the PYPI_PASSWORD contain newlines in it, which breaks the `twine upload ...` command into several pieces. This can happen, for example, when copy/pasting from doing a `echo $PYPI_TOKEN | pbcopy` since the echo adds a newline. Try copying the pypi token again and ensure there’s no newline in it. ## Github token problems (e.g. tagging) At the point of writing this, some jobs don’t fail when there are (non-essential) errors. One hidden problem that you might get in when “Tag Repository With New Version Number” does a `Run isee tag-repo $VERSION`. You’ll get: ```default remote: Permission to thorwhalen/sung.git denied to github-actions[bot]. fatal: unable to access 'https://github.com/thorwhalen/sung/': The requested URL returned error: 403 Error executing git command: Command 'git --git-dir="/home/runner/work/sung/sung/.git" --work-tree="/home/runner/work/sung/sung" push origin 0.0.16' returned non-zero exit status 128. Standard output: Exit code: 128 ``` Top cause and solution: * Check Repository Permissions: Ensure that the `GITHUB_TOKEN` has the necessary permissions (i.e. read **and write**) to push to the repository. You can configure this in the repository settings under Actions -> General -> Workflow permissions (`https://github.com/{username_or_org}/{repo}/settings/actions`). ![image](https://github.com/user-attachments/assets/0a35c514-216c-4616-92fa-b8978762594c) Other possible problesm: * Verify SSH keys: Did you put a ssh public key, and a corresponding SSH_PRIVATE_KEY in your environment), and are they correct? Global ssh public keys can be managed [here in user or org level settings](https://github.com/settings/keys). Set repository secrets (envoronment variable) here: `https://github.com/{username_or_org}/{repo}/settings/secrets/actions`. * Review the Token Usage * Check Branch Protection Rules ## Version tag misalignment (Note: Normally this shouldn’t happen anymore, since I included a “version alignment” logic in [get_new_version](https://github.com/i2mint/isee/blob/master/isee/generation_utils.py), which is used in the [bump-version-number action](https://github.com/i2mint/isee/blob/master/actions/bump-version-number/action.yml) via `gen_semver`. Still, I’ll keep this around for historical reasons.) Sometimes the twine PYPI publishing may fail with such a message: ```default WARNING Skipping PKGNAME-0.1.4-py3-none-any.whl because it appears to already exist WARNING Skipping PKGNAME-0.1.4.tar.gz because it appears to already exist ``` This often means that your git tags are misaligned with the `pyproject.toml` (or in older versions, `setup.cfg`) version. You can see your git tags here: `https://github.com/ORG/REPO/tags`. To repair, do this: * go to the https://pypi.org/project/ project page and note the PYPI_VERSION number * got to `setup.cfg` and see what version is there, called it SETUP_VERSION * make a NEW_VERSION, which is a version number ABOVE the SETUP_VERSION and PYPI_VERSION. * edit the `setup.cfg` so it shows NEW_VERSION * `git tag NEW_VERSION` * `git push origin NEW_VERSION` Sometimes I need to update the setup version again, and push again.

This documentation as a single file: isee.md (Markdown, for agents).

# _autosummary/isee.common.html.md # isee.common This module contains common functions that are used in multiple modules. Functions: - git: Execute a git command and return the output. - get_env_var: Get the value of an environment variable. - get_file_path: Get the file path of a file in a directory. ### Functions | [`get_env_var`](_autosummary/isee.common.html.md#isee.common.get_env_var)(key) | Get the value of an environment variable. | |------------------------------------------------------------------------------------|----------------------------------------------| | `get_file_path`(filename, root_path) | | | [`git`](_autosummary/isee.common.html.md#isee.common.git)(\*args[, work_tree, git_dir]) | Execute a git command and return the output. | ### isee.common.get_env_var(key) Get the value of an environment variable. If the variable is not defined or is empty, raise a RuntimeError. * **Parameters:** **key** – The name of the environment variable. * **Returns:** The value of the environment variable. * **Raises:** [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If the environment variable is not defined or is empty. ```pycon >>> import os >>> os.environ['TEST'] = 'test' >>> get_env_var('TEST') 'test' ``` ```pycon >>> get_env_var('TEST2') Traceback (most recent call last): ... RuntimeError: TEST2 is not defined or is empty! ``` ```pycon >>> os.environ['TEST3'] = '' >>> get_env_var('TEST3') Traceback (most recent call last): ... RuntimeError: TEST3 is not defined or is empty! ``` ### isee.common.git(\*args, work_tree='.', git_dir=None) Execute a git command and return the output. ```pycon >>> git('status') On branch master Your branch is up to date with 'origin/master'. nothing to commit, working tree clean ``` # _autosummary/isee.file_modification_utils.html.md # isee.file_modification_utils This module provides utilities for updating files. Functions: - update_helm_tpl: Update the Helm chart template files. - update_manifest: Update the manifest file. - update_setup_cfg: Update the setup.cfg file. - update_setup_py: Update the setup.py file. - \_get_setup_filepath: Get the setup file path. - \_update_file: Update the file content. ### Functions | `update_helm_tpl`() | | |--------------------------------------------------------------------------------------------------|--------------------------------------------| | `update_manifest`(manifest_path) | | | [`update_pyproject_toml`](_autosummary/isee.file_modification_utils.html.md#isee.file_modification_utils.update_pyproject_toml)(\*[, file_path, ...]) | Update the version in pyproject.toml file. | | [`update_setup_cfg`](_autosummary/isee.file_modification_utils.html.md#isee.file_modification_utils.update_setup_cfg)(\*[, file_path, version, ...]) | Update the version in setup.cfg file. | | `update_setup_py`(\*[, project_dir, version]) | | ### isee.file_modification_utils.update_pyproject_toml(, file_path=None, version=None, pkg_dir='.') Update the version in pyproject.toml file. * **Parameters:** * **file_path** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Deprecated) Path to the config file. Use pkg_dir instead. * **version** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The version to set. If None, tries to get it from the VERSION environment variable. * **pkg_dir** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Directory containing the package config files (default: current directory) ### isee.file_modification_utils.update_setup_cfg(, file_path=None, version=None, pkg_dir='.') Update the version in setup.cfg file. #### NOTE This function is deprecated. For new projects using pyproject.toml, use update_pyproject_toml instead. This function is kept for backward compatibility. * **Parameters:** * **file_path** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Deprecated) Path to the config file. Use pkg_dir instead. * **version** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The version to set. If None, tries to get it from the VERSION environment variable. * **pkg_dir** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Directory containing the package config files (default: current directory) # _autosummary/isee.generation_utils.html.md # isee.generation_utils Generation utils for the isee package. Main function: - gen_semver: Generate a new semantic version based on git commit messages and tags. Documentation generation used to live here too; it moved out to `i2mint/epythet/actions/publish-github-pages`, which is what this repo’s own CI uses. ### Functions | [`gen_semver`](_autosummary/isee.generation_utils.html.md#isee.generation_utils.gen_semver)(\*[, dir_path, ...]) | Generate a new semantic version based on git commit messages and tags. | |----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------| | [`get_new_version`](_autosummary/isee.generation_utils.html.md#isee.generation_utils.get_new_version)(\*[, work_tree, ...]) | Get the latest version from git tags and determine the new version based on the commit message. | ### isee.generation_utils.gen_semver(, dir_path=None, version_patch_prefix='', output_mode='auto') Generate a new semantic version based on git commit messages and tags. ### Args - dir_path (str): The directory path where the git repository is located. : If None, uses the current directory. - version_patch_prefix (str): A prefix to be added to the patch version. - output_mode (str): How to output the version: : - “auto”: Detect if running in GitHub Actions and adjust accordingly - “print”: Only print to stdout (for shell capture) - “return”: Only return (for Python API use) - “both”: Both print and return ### Returns - str: The new version string if output_mode is “return” or “both”. - None: If output_mode is “print”. ### isee.generation_utils.get_new_version(\*, work_tree='.', version_patch_prefix='', action_when_versions_not_valid=) Get the latest version from git tags and determine the new version based on the commit message. # _autosummary/isee.git_utils.html.md # isee.git_utils Utilities for working with git repositories. Functions: - tag_repo: Tag the git repository with a new tag and push it to the remote repository. ### Functions | `tag_repo`(tag, \*[, git_dir]) | | |----------------------------------|----| # _autosummary/isee.html.md # isee Tools for CI ### Module Attributes | [`COMMANDS`](_autosummary/isee.html.md#isee.COMMANDS) | The commands `isee` exposes, in the order they appear in `isee --help`. | |-------------------------------------------------------------|---------------------------------------------------------------------------| ### Functions | [`main`](_autosummary/isee.html.md#isee.main)() | Entry point of the `isee` console script. | |-----------------------------------------------------------|---------------------------------------------| ### isee.COMMANDS *= [, , , , , , , , ]* The commands `isee` exposes, in the order they appear in `isee --help`. Eight GitHub Action definitions in this repo invoke them by name, so this list – and every flag these functions’ signatures imply – is a public interface, pinned by `tests/test_cli_surface.py`. ### isee.main() Entry point of the `isee` console script. ### Modules | [`common`](_autosummary/isee.common.html.md#module-isee.common) | This module contains common functions that are used in multiple modules. | |--------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | [`file_modification_utils`](_autosummary/isee.file_modification_utils.html.md#module-isee.file_modification_utils) | This module provides utilities for updating files. | | [`generation_utils`](_autosummary/isee.generation_utils.html.md#module-isee.generation_utils) | Generation utils for the isee package. | | [`git_utils`](_autosummary/isee.git_utils.html.md#module-isee.git_utils) | Utilities for working with git repositories. | | [`local_cli`](_autosummary/isee.local_cli.html.md#module-isee.local_cli) | Run GitHub Actions workflows locally using act. | | [`pip_utils`](_autosummary/isee.pip_utils.html.md#module-isee.pip_utils) | Utilities for reading a project's declared dependencies and installing them. | | [`pylint_log_synopsis`](_autosummary/isee.pylint_log_synopsis.html.md#module-isee.pylint_log_synopsis) | This module provides utilities for working with pylint logs. | # _autosummary/isee.local_cli.html.md # isee.local_cli Run GitHub Actions workflows locally using act. This module automates running your CI pipeline locally before pushing to GitHub. It checks for required dependencies (act, Docker) and provides clear setup instructions if anything is missing. Usage: ```text # Check if everything is set up python -m isee.local_cli --check-deps # Run entire CI workflow (fast, clean - no local artifacts) python -m isee.local_cli # Run with local artifacts for debugging python -m isee.local_cli --bind # Run just validation job (all matrix combinations) python -m isee.local_cli -j validation # Run specific matrix combination python -m isee.local_cli -j validation -m python-version:3.12 # For M-series Macs (if needed) python -m isee.local_cli --container-arch linux/amd64 # See what would run without executing python -m isee.local_cli --dry-run # Quiet mode (less output) python -m isee.local_cli -q ``` ### Functions | [`check_dependencies`](_autosummary/isee.local_cli.html.md#isee.local_cli.check_dependencies)(\*[, verbose]) | Check if act and Docker are available and provide setup instructions if not. | |---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| | [`main`](_autosummary/isee.local_cli.html.md#isee.local_cli.main)() | CLI entry point for running CI locally. | | [`run_ci`](_autosummary/isee.local_cli.html.md#isee.local_cli.run_ci)(\*[, job, matrix, dry_run, ...]) | Run CI workflow locally using act. | | [`run_workflow_locally`](_autosummary/isee.local_cli.html.md#isee.local_cli.run_workflow_locally)([workflow_path, bind, ...]) | Run a GitHub Actions workflow locally using act. | ### isee.local_cli.check_dependencies(, verbose=True) Check if act and Docker are available and provide setup instructions if not. * **Returns:** bool, missing: list[str]) * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`bool`](https://docs.python.org/3/builtins/functions.html#bool), [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ```pycon >>> ready, missing = check_dependencies(verbose=False) >>> isinstance(ready, bool) and isinstance(missing, list) True ``` ### isee.local_cli.main() CLI entry point for running CI locally. ### isee.local_cli.run_ci(, job=None, matrix=None, dry_run=False, workflow_file='.github/workflows/ci.yml', verbose=True, bind=False, container_arch=None) Run CI workflow locally using act. * **Parameters:** * **job** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Specific job to run (e.g., ‘validation’). If None, runs all jobs. * **matrix** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Matrix combination (e.g., ‘python-version:3.12’). Requires job to be set. * **dry_run** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, list what would run without executing. * **workflow_file** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path to workflow file to run. * **verbose** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, print progress information. * **bind** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Mount working directory (creates local artifacts like dist/). * **container_arch** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Container architecture (e.g., ‘linux/amd64’ for M-series Macs). * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) * **Returns:** Exit code (0 for success, non-zero for failure). ### Examples ```pycon >>> # These examples don't actually run act, just demonstrate the interface >>> # run_ci(job='validation', matrix='python-version:3.12') # Run one matrix combo >>> # run_ci(job='validation') # Run all validation matrix combos >>> # run_ci(dry_run=True) # See what would run ``` ### isee.local_cli.run_workflow_locally(workflow_path=None, , bind=False, keep_container=False, container_architecture=None) Run a GitHub Actions workflow locally using act. * **Parameters:** * **workflow_path** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path to workflow file (if None, auto-detects) * **bind** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Mount working directory into container (creates local artifacts) * **keep_container** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Keep container after run for debugging * **container_architecture** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Container architecture (e.g., ‘linux/amd64’) * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) # _autosummary/isee.pip_utils.html.md # isee.pip_utils Utilities for reading a project’s declared dependencies and installing them. These functions back the `isee install-requires` and `isee tests-require` CLI commands (and therefore the `install-packages` action). They understand both modern `pyproject.toml` (PEP 621 `[project]`) and legacy `setup.cfg` projects, preferring `pyproject.toml` whenever it declares a `[project]` table. Functions: - install_requires: Install the project’s runtime dependencies. - tests_require: Install the project’s test dependencies. - resolve_install_requires: Resolve (without installing) the runtime deps. - resolve_tests_require: Resolve (without installing) the test deps. - read_setup_config: (legacy) Read the setup.cfg file in the project directory. - build_dependency_wheels: Build dependency wheels for the project. - extras_require / install_extras: (legacy) setup.cfg extras_require helpers. ### Module Attributes | [`SETUP_CFG_ENCODING`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.SETUP_CFG_ENCODING) | `setup.cfg` is read as UTF-8, whatever the locale says -- the same reasoning as `_update_file`'s explicit encoding: otherwise a non-ASCII byte crashes the read under a C/POSIX locale, or (e.g. U+0141 in cp1252) on a Windows runner. | |-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ### Functions | `build_dependency_wheels`(repository_dir, ...) | | |------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | [`extras_require`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.extras_require)([name, project_dir]) | Return a list of packages for the given extras_require key (e.g. 'testing'). | | [`install_extras`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.install_extras)([name, project_dir]) | Install packages listed under extras_require[name] in setup.cfg. | | `install_packages_from_options`(...) | | | [`install_requires`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.install_requires)(\*[, project_dir]) | Install the project's runtime dependencies. | | [`read_setup_config`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.read_setup_config)([project_dir]) | (legacy) Read and return the `setup.cfg` ConfigParser for the project. | | [`resolve_install_requires`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.resolve_install_requires)(\*[, project_dir]) | Return the project's runtime dependencies as a list of requirement strings. | | [`resolve_tests_require`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.resolve_tests_require)(\*[, project_dir, ...]) | Return the project's test dependencies as a list of requirement strings. | | [`tests_require`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.tests_require)(\*[, project_dir, test_extras]) | Install the project's test dependencies. | ### isee.pip_utils.SETUP_CFG_ENCODING *= 'utf-8'* `setup.cfg` is read as UTF-8, whatever the locale says – the same reasoning as `_update_file`’s explicit encoding: otherwise a non-ASCII byte crashes the read under a C/POSIX locale, or (e.g. U+0141 in cp1252) on a Windows runner. ### isee.pip_utils.extras_require(name='testing', , project_dir=None) Return a list of packages for the given extras_require key (e.g. ‘testing’). If setup.cfg or the section/key is missing return an empty list instead of raising so callers can safely act on the result. ### isee.pip_utils.install_extras(name='testing', , project_dir=None) Install packages listed under extras_require[name] in setup.cfg. This is a convenience wrapper used by CI when present. If no packages are found the function prints a message and does nothing. ### isee.pip_utils.install_requires(, project_dir=None) Install the project’s runtime dependencies. Reads them from `pyproject.toml` `[project].dependencies` when present, otherwise `setup.cfg` `[options] install_requires`. ### isee.pip_utils.read_setup_config(project_dir=None) (legacy) Read and return the `setup.cfg` ConfigParser for the project. Prefer [`resolve_install_requires()`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.resolve_install_requires) / [`resolve_tests_require()`](_autosummary/isee.pip_utils.html.md#isee.pip_utils.resolve_tests_require), which also understand `pyproject.toml`. ### isee.pip_utils.resolve_install_requires(, project_dir=None) Return the project’s runtime dependencies as a list of requirement strings. Reads `[project].dependencies` from `pyproject.toml` when present, otherwise `[options] install_requires` from `setup.cfg`. Raises a `RuntimeError` only when neither metadata file exists. ### isee.pip_utils.resolve_tests_require(, project_dir=None, test_extras=('testing', 'test', 'tests', 'dev')) Return the project’s test dependencies as a list of requirement strings. Reads `[project.optional-dependencies]` from `pyproject.toml` (the first of `test_extras` that is present) when a `[project]` table exists, otherwise `[options] tests_require` from `setup.cfg`. Raises a `RuntimeError` only when neither metadata file exists. ### isee.pip_utils.tests_require(, project_dir=None, test_extras=('testing', 'test', 'tests', 'dev')) Install the project’s test dependencies. Reads them from `pyproject.toml` `[project.optional-dependencies]` (the first present of `test_extras`) when present, otherwise `setup.cfg` `[options] tests_require`. # _autosummary/isee.pylint_log_synopsis.html.md # isee.pylint_log_synopsis This module provides utilities for working with pylint logs. Functions: - parsed_lines: Parse the pylint log lines. - missing_import_module: Get the missing import module from the log message. - process_parsed_line: Process the parsed line to get the missing package or module. - analyze_log: Analyze the pylint log to get the missing packages and modules. - log_analysis_string: Generate a string report of the missing packages and modules. - print_log_analysis: Print the string report of the missing packages and modules. - print_report_followed_by_log: Print the string report followed by the pylint log. Notes (TODO): I’d rather have a “here’s what you got to do” synopsis. For example, consider the log below versus the following synopsis of it. Synopsis: ```text Missing module docstrings in: - __init__.py - snippers.py Missing packages: - sklearn - matplotlib - pandas ``` Log: ```text Run pylint ./$PROJECT_NAME --ignore=tests,examples,scrap --disable=all --enable=C0114,E0401 ************* Module slang slang/__init__.py:1:0: C0114: Missing module docstring (missing-module-docstring) ************* Module slang.snippers slang/snippers.py:1:0: C0114: Missing module docstring (missing-module-docstring) slang/snippers.py:6:0: E0401: Unable to import 'sklearn.decomposition' (import-error) slang/snippers.py:7:0: E0401: Unable to import 'sklearn.discriminant_analysis' (import-error) slang/snippers.py:8:0: E0401: Unable to import 'sklearn.cluster' (import-error) ************* Module slang.spectrop slang/spectrop.py:1:0: C0114: Missing module docstring (missing-module-docstring) slang/spectrop.py:7:0: E0401: Unable to import 'sklearn.decomposition' (import-error) slang/spectrop.py:8:0: E0401: Unable to import 'sklearn.discriminant_analysis' (import-error) slang/spectrop.py:9:0: E0401: Unable to import 'sklearn.utils.validation' (import-error) slang/spectrop.py:10:0: E0401: Unable to import 'sklearn.base' (import-error) slang/spectrop.py:503:0: E0401: Unable to import 'sklearn.neighbors' (import-error) slang/spectrop.py:504:0: E0401: Unable to import 'sklearn.discriminant_analysis' (import-error) slang/spectrop.py:505:0: E0401: Unable to import 'sklearn.decomposition' (import-error) slang/spectrop.py:506:0: E0401: Unable to import 'sklearn.linear_model' (import-error) ************* Module slang.snip_stats slang/snip_stats.py:1:0: C0114: Missing module docstring (missing-module-docstring) slang/snip_stats.py:6:0: E0401: Unable to import 'matplotlib.pylab' (import-error) slang/snip_stats.py:8:0: E0401: Unable to import 'pandas' (import-error) slang/snip_stats.py:9:0: E0401: Unable to import 'sklearn.base' (import-error) ----------------------------------- Your code has been rated at 9.42/10 Error: Process completed with exit code 18. ``` I’d still want the verbose output. But a synopsis report would more immediately useful. [https://github.com/i2mint/unbox](https://github.com/i2mint/unbox) has a function that compares deps of setup.cfg versus imports to give a list of missing third party packages. That could be used (though different from E0401). But perhaps a log parser would be better, more generally useable. Perhaps pylint already has such a synopsis report maker? ### Functions | `analyze_log`(log_string) | | |----------------------------------------------|----| | `log_analysis_string`(log_string) | | | `missing_import_module`(msg) | | | `parsed_lines`(log_string) | | | `print_log_analysis`(log_string) | | | `print_report_followed_by_log`([log_string]) | | | `process_parsed_line`(parsed) | | # about-this-build.html.md # About this build This documentation was built on **2026-10-13 11:17 UTC** from commit 3a3895f on branch master, for **isee 0.2.82** (from pyproject.toml). #### NOTE Nothing suggests a mismatch: the tree was clean at the commit above, and the documented version is the one on PyPI. ## Source | | | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | Commit | 3a3895fc8efea81dc562d245e722e871e755bfcd | | Branch | master | | Tags at this commit | 0.2.82 | | Working tree | clean | | Remote | https://github.com/i2mint/isee | ## Continuous integration | | | |--------------|--------------------------------------------------------------------------------------------| | Repository | i2mint/isee | | Run | 38389008304 | | Ref | refs/heads/master | | Event commit | 996d29f0490c2a989785d7313fc8087ceb0e3c76 (in the history of the built commit) | ## Tools | | | |----------|---------| | epythet | 0.2.15 | | Sphinx | 9.1.0 | | docutils | 0.22.4 | | Python | 3.12.15 | ## Configuration as resolved | | | |---------------|------------------------------------------------------------------| | theme | auto (Sphinx theme furo) | | accent | #006a7b | | api_generator | autosummary | | ignore | tests/, scrap/, examples/ | | agent_outputs | true | | aggregates | md | | ai_artifacts | true | ## Package on PyPI Latest release: 0.2.82, the same as the documented version. ## Reproduce ```bash git clone https://github.com/i2mint/isee && cd isee git checkout 3a3895fc8efea81dc562d245e722e871e755bfcd pip install "epythet==0.2.15" epythet quickstart . --ignore tests/ scrap/ examples/ ``` The same data, for machines: build_info.json (schema version 1). # api.html.md # API reference | [`isee`](_autosummary/isee.html.md#module-isee) | Tools for CI | |---------------------------------------------------------------------|----------------|