PythonCommons

Common software utilities and architecture tools for neutrons Python projects. This repository provides only reusable infrastructure components.

Purpose

This package centralizes cross-cutting architectural concerns that are useful across multiple neutrons projects:

• Configuration Management (config.py) - YAML-based configuration with environment layering and token substitution
• Singleton Pattern (singleton.py) - Decorator for enforcing single-instance patterns
• Time Utilities (time.py) - High-precision timestamp generation and parsing
• Other infrastructure utilities and design patterns

Domain-specific scientific utilities should be implemented in project-specific repositories, not here.

Quick Start

Install Pixi

curl -fsSL https://pixi.sh/install.sh | bash

Set Up Environment

pixi install

Run Tests

pixi run test

Using This Package

Add PythonCommons as a dependency to your project:

# In your pyproject.toml
dependencies = [
    "PythonCommons @ git+https://github.com/neutrons/PythonCommons.git",
]

or

[tool.pixi.workspace]
channels = [
  "neutrons",
  "conda-forge",
  "conda-forge",
  "https://prefix.dev/pixi-build-backends",
]

[tool.pixi.dependencies]
neutrons_standard = "*"

[tool.pixi.package.run-dependencies]
neutrons_standard = "*"

Then import utilities:

from neutrons_standard import Config
from neutrons_standard.decorators.singleton import Singleton
from neutrons_standard.time import timestamp, isoFromTimestamp

See readthedocs for detailed documentation on each module.

Development

Available Tasks

pixi run         # List all tasks
pixi run test    # Run tests
pixi run build-docs  # Build documentation

Development Workflow

pixi shell                      # Activate environment
python -m pytest tests/         # Run tests
ruff check .                    # Lint code

Testing

Run the test suite:

pixi run test

Tests are located in tests/ and use pytest.

Documentation

Documentation is built with Sphinx:

pixi run build-docs

Output will be in docs/_build/html/.

Project Structure

PythonCommons/
├── src/neutrons_standard/              # Main package
│   ├── config.py             # Configuration management
│   ├── time.py               # Time utilities
│   └── decorators/
│       └── singleton.py       # Singleton pattern decorator
├── tests/                    # Test suite
├── docs/                     # Documentation (Sphinx)
├── pyproject.toml            # Project metadata and Pixi tasks
└── pixi.lock                 # Locked dependencies

Known Issues

SQLite file locking on shared mounts

On SNS Analysis systems, pixi run conda-build may fail due to sqlite3 file locking on shared mounts. This is a known limitation when user directories are network shares.

Dynamic versioning and lock file circular dependency

When using pixi with editable self-dependencies and git-based versioning, there's a circular dependency issue. The solution uses pixi's --skip flag:

pixi install --frozen --skip PythonCommons
pip install --no-deps -e .