Core development workflow

This page walks you through getting apexinfosysindia/core running from a source checkout.

Prerequisites

• Python 3.14.2 or newer — core declares requires-python = ">=3.14.2" in pyproject.toml. Older interpreters will not install.
• A Linux or macOS shell (CI runs on Ubuntu; the dev container is Linux-based).
• uv is recommended — the setup scripts use it when available and fall back to the standard tooling otherwise.

Quick start: script/setup

Clone your fork and run the repository's setup script from the repo root:

git clone https://github.com/<your-username>/core.git
cd core
script/setup

script/setup does everything in one shot:

1. Copies default VS Code settings into .vscode/settings.json if you don't have any.

2. Creates a .venv virtual environment (via uv venv when uv is installed, else python3 -m venv) and activates it.

3. Runs script/bootstrap, which installs the development dependencies:

   uv pip install \
     -e . \
     -r requirements_all.txt \
     -r requirements_test.txt \
     colorlog \
     --upgrade \
     --config-settings editable_mode=compat

   Note the editable install (-e .) — your source edits take effect without reinstalling.

4. Compiles the English translations: python3 -m script.translations develop --all. Tests and the UI read from the generated translations/en.json files, not from strings.json directly, so re-run this (or the --integration <name> variant) after editing any strings.json.

5. Installs the git hooks with prek install, so lint runs automatically on commit.

6. Creates a local config/ directory and seeds it with apex --script ensure_config -c config, adding a default logger: block to configuration.yaml.

Manual setup

If you prefer to do it by hand, the equivalent minimal steps are:

python3.14 -m venv .venv
source .venv/bin/activate
pip install uv
uv pip install -e . -r requirements_test.txt

requirements_all.txt (every integration's dependencies) is large; you can skip it and instead install only what a specific integration needs:

python3 -m script.install_integration_requirements <domain>

Running core locally

The editable install exposes the console script apex (defined in pyproject.toml as apex = "apexos.__main__:main"). Running the package module directly, python -m apexos, is equivalent.

# Run against the repo-local config directory created by script/setup
apex -c config

# Or explicitly via the module
python -m apexos -c config

• -c / --config points at the configuration directory. If you omit it, the default is ~/.apexos in your home directory.
• apex --script ensure_config -c config creates the directory and a starter configuration.yaml without starting the server.
• If the configuration directory doesn't exist and isn't the default, startup aborts with a fatal error — create it first (or let ensure_config do it).

On first start the frontend is served locally and you can walk through onboarding in the browser.

Running tests for a single integration

You rarely need the full test suite locally. Target the integration you're working on:

python3 -m pytest tests/components/<domain>

For coverage output matching what CI checks:

python3 -m pytest tests/components/<domain> \
  --cov=apexos.components.<domain> \
  --cov-report=term-missing

See Testing for the fixtures, layout, and the exact flags CI uses.

Linting your changes

script/lint runs Ruff (through prek) and pylint against only the Python files changed on your branch — a fast pre-push sanity check. The commit-time hooks installed by prek install cover formatting automatically.