Warning
We don't accept pull requests from outside contributors. Pull requests opened by anyone outside the team are closed without review. If you've found a bug or have an idea, open an issue or start a discussion instead, as described in the main contributing guide.
This guide is for Datist team members working on Fairspec Python.
Project is a monorepo with the following packages:
fairspec-metadata: Core metadata models and descriptorsfairspec-dataset: File, folder and stream I/O plus dataset source pluginsfairspec-table: Polars-backed table engine plus file format pluginsfairspec-library: All the above functionality behind one plugin registryfairspec-mcp-server: MCP tools over the library actionsfairspec-terminal: Terminal interfacefairspec: Meta-package that re-exports the underlying functionality
- Python: v3.12 or higher
- uv: v0.7.0 or higher
- Node: v24.11.0 or higher, with pnpm v11 (the repo scripts run through pnpm)
-
Clone the repository
git clone https://github.com/datisthq/fairspec.git cd fairspec -
Install dependencies
pnpm install
We use Ruff for linting and formatting, and ty for type checking:
-
Lint: Check for code issues
pnpm -C python check:lint
-
Format: Auto-fix formatting issues
pnpm -C python format
-
Type Check: Verify Python types
pnpm -C python check:types
Tests are collocated with the code in _test directories and use pytest:
-
Run All Tests: (includes linting and type checking)
pnpm -C python test -
Run Tests Only: (without linting/type checking)
pnpm -C python test:unit
-
Run a Specific Test:
pnpm -C python test:unit metadata/fairspec_metadata/actions/descriptor/_test/load_unit.py
- Use Python with strict type checking
- Target Python 3.12+
- Tests should be placed in
*_unit.pyfiles inside a_testdirectory next to the code, together with anyfixturesthey need - Use 4-space indentation, UTF-8 encoding, and LF line endings
- Use PascalCase for classes, snake_case for functions, methods, and variables
See the root AGENTS.md and the python-development skill in .agents/skills/ for the full
set of conventions.
When adding new functionality:
- Add it to the appropriate package first
- Ensure it's properly exported from that package
- No additional work is needed for the meta-package as it automatically re-exports everything
- Create a feature branch (
git checkout -b feature/your-feature) - Make your changes with appropriate tests
- Ensure the code passes all checks:
pnpm -C python test - Commit your changes with a descriptive message
- Submit a pull request
By contributing to Fairspec Python, you agree that your contributions will be licensed under the project's license.
Thank you for your contribution!