{"id":30668117,"url":"https://github.com/datumbrain/python","last_synced_at":"2025-10-05T17:28:10.162Z","repository":{"id":312080547,"uuid":"1046219807","full_name":"datumbrain/python","owner":"datumbrain","description":"Company-wide Python project configuration files.","archived":false,"fork":false,"pushed_at":"2025-08-28T11:31:44.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T18:39:59.919Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datumbrain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-28T11:15:07.000Z","updated_at":"2025-08-28T11:31:47.000Z","dependencies_parsed_at":"2025-08-28T18:40:02.957Z","dependency_job_id":"44154a86-e914-48ac-91c2-89624aa945d6","html_url":"https://github.com/datumbrain/python","commit_stats":null,"previous_names":["datumbrain/python"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/datumbrain/python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fpython","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fpython/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fpython/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fpython/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datumbrain","download_url":"https://codeload.github.com/datumbrain/python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fpython/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278486690,"owners_count":25995025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-31T23:09:21.124Z","updated_at":"2025-10-05T17:28:10.130Z","avatar_url":"https://github.com/datumbrain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Project Standards / Datum Brain\n\nThis repository contains the company-wide standard configuration files and project structure for Python projects at DatumBrain. These standards ensure consistency, maintainability, and quality across all Python projects.\n\n## 📋 Overview\n\nThis template provides a standardized setup for Python projects including:\n\n- **Code quality tools** (Ruff, Black, MyPy)\n- **Testing framework** (Pytest with coverage)\n- **Project structure** (src layout)\n- **Configuration files** (pyproject.toml, .gitignore, .editorconfig)\n\n## 🚀 Quick Start\n\n### Using this Template\n\n1. Clone this repository as a template for your new project:\n\n   ```bash\n   git clone https://github.com/datumbrain/python-template your-project-name\n   cd your-project-name\n   ```\n\n2. Update project-specific details:\n\n   - Rename `src/your_package_name` to your actual package name\n   - Update package name references in `pyproject.toml`\n   - Update author information and project metadata\n\n3. Install Poetry (if not already installed):\n\n   ```bash\n   curl -sSL https://install.python-poetry.org | python3 -\n   ```\n\n4. Install dependencies:\n\n   ```bash\n   poetry install\n   ```\n\n5. Activate the virtual environment:\n\n   ```bash\n   poetry shell\n   ```\n\n## 📁 Project Structure\n\n```raw\n.\n├── src/                    # Source code directory\n│   └── your_package_name/  # Your main package\n│       └── __init__.py     # Package initialization\n├── tests/                  # Test directory\n│   ├── __init__.py        # Test package initialization\n│   └── conftest.py        # Pytest configuration and fixtures\n├── .editorconfig          # Editor configuration for consistency\n├── .gitignore             # Git ignore patterns\n├── pyproject.toml         # Project configuration and dependencies\n└── README.md              # Project documentation\n```\n\n### Directory Explanations\n\n- **`src/`**: Contains all production code. Using src layout prevents accidentally importing from the repository root.\n- **`tests/`**: Contains all test files. Tests should mirror the structure of the src directory.\n- **`.editorconfig`**: Ensures consistent coding styles between different editors and IDEs.\n- **`pyproject.toml`**: Central configuration file for the project, including dependencies, build system, and tool configurations.\n\n## 🛠️ Configuration Files\n\n### pyproject.toml\n\nThe `pyproject.toml` file is the central configuration hub containing:\n\n- **Project metadata**: Name, version, description, authors\n- **Dependencies**: Using Poetry for dependency management\n- **Tool configurations**:\n  - **Ruff**: Fast Python linter and formatter\n  - **MyPy**: Static type checking\n  - **Pytest**: Testing framework configuration\n  - **Coverage**: Code coverage settings\n  - **Black**: Code formatting (optional, alongside Ruff)\n\n### .gitignore\n\nComprehensive gitignore file covering:\n\n- Python artifacts (`__pycache__`, `*.pyc`, etc.)\n- Virtual environments (`venv`, `.venv`, etc.)\n- IDE files (`.idea`, `.vscode`)\n- Test and coverage reports\n- OS-specific files (`.DS_Store`, `Thumbs.db`)\n\n### .editorconfig\n\nStandardizes:\n\n- Character encoding (UTF-8)\n- Line endings (LF for Unix-style)\n- Indentation (4 spaces for Python)\n- Trailing whitespace handling\n- File-specific settings for YAML, JSON, Markdown, etc.\n\n## 🧰 Development Tools\n\n### Code Quality\n\n#### Ruff (Linting and Formatting)\n\n```bash\n# Run linter\npoetry run ruff check .\n\n# Fix auto-fixable issues\npoetry run ruff check --fix .\n\n# Format code\npoetry run ruff format .\n```\n\n#### MyPy (Type Checking)\n\n```bash\npoetry run mypy src\n```\n\n#### Black (Alternative Formatter)\n\n```bash\npoetry run black src tests\n```\n\n### Testing\n\n#### Run Tests\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov\n\n# Run specific test file\npoetry run pytest tests/test_module.py\n\n# Run tests in parallel\npoetry run pytest -n auto\n```\n\n#### Test Markers\n\n```bash\n# Run only unit tests\npoetry run pytest -m unit\n\n# Skip slow tests\npoetry run pytest -m \"not slow\"\n\n# Run integration tests\npoetry run pytest -m integration\n```\n\n### Pre-commit Hooks\n\nSet up pre-commit hooks to automatically run checks before commits:\n\n```bash\n# Install pre-commit\npoetry add --group dev pre-commit\n\n# Create .pre-commit-config.yaml\ncat \u003e .pre-commit-config.yaml \u003c\u003c EOF\nrepos:\n  - repo: https://github.com/astral-sh/ruff-pre-commit\n    rev: v0.1.0\n    hooks:\n      - id: ruff\n        args: [--fix]\n      - id: ruff-format\n  - repo: https://github.com/pre-commit/mirrors-mypy\n    rev: v1.5.0\n    hooks:\n      - id: mypy\n        additional_dependencies: [types-all]\nEOF\n\n# Install the git hook scripts\npoetry run pre-commit install\n\n# Run against all files (first time)\npoetry run pre-commit run --all-files\n```\n\n## 📏 Coding Standards\n\n### Style Guide\n\n- **Line Length**: 88 characters (Black/Ruff default)\n- **Indentation**: 4 spaces\n- **Quotes**: Double quotes for strings\n- **Imports**: Sorted and grouped (via Ruff/isort)\n- **Docstrings**: Google style convention\n\n### Type Hints\n\nAll new code should include type hints:\n\n```python\ndef calculate_total(items: list[float], tax_rate: float = 0.1) -\u003e float:\n    \"\"\"Calculate total with tax.\n\n    Args:\n        items: List of item prices.\n        tax_rate: Tax rate to apply.\n\n    Returns:\n        Total amount including tax.\n    \"\"\"\n    subtotal = sum(items)\n    return subtotal * (1 + tax_rate)\n```\n\n### Testing Standards\n\n- Minimum 80% code coverage\n- Tests organized in `tests/` mirroring `src/` structure\n- Use pytest fixtures for reusable test data\n- Descriptive test names: `test_\u003cfunction\u003e_\u003cscenario\u003e_\u003cexpected_outcome\u003e`\n\n## 🔄 Workflow\n\n### Development Workflow\n\n1. Create a feature branch:\n\n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n\n2. Make your changes in `src/`\n\n3. Write/update tests in `tests/`\n\n4. Run quality checks:\n\n   ```bash\n   poetry run ruff check .\n   poetry run ruff format .\n   poetry run mypy src\n   poetry run pytest --cov\n   ```\n\n5. Commit your changes:\n\n   ```bash\n   git add .\n   git commit -m \"feat: add your feature description\"\n   ```\n\n6. Push and create a pull request\n\n### Commit Message Convention\n\nFollow conventional commits:\n\n- `feat:` New feature\n- `fix:` Bug fix\n- `docs:` Documentation changes\n- `style:` Code style changes (formatting)\n- `refactor:` Code refactoring\n- `test:` Test changes\n- `chore:` Build process or auxiliary tool changes\n\n## 📦 Building and Publishing\n\n### Building the Package\n\n```bash\npoetry build\n```\n\nThis creates distribution files in the `dist/` directory.\n\n### Publishing to PyPI\n\n```bash\n# Configure PyPI token\npoetry config pypi-token.pypi your-token\n\n# Publish\npoetry publish\n```\n\n### Publishing to Private Repository\n\n```bash\n# Configure private repository\npoetry config repositories.private https://your-repo-url\npoetry config http-basic.private username password\n\n# Publish\npoetry publish -r private\n```\n\n## 🔍 Common Tasks\n\n### Adding Dependencies\n\n```bash\n# Add production dependency\npoetry add package-name\n\n# Add development dependency\npoetry add --group dev package-name\n\n# Add specific version\npoetry add package-name@^2.0.0\n```\n\n### Updating Dependencies\n\n```bash\n# Update all dependencies\npoetry update\n\n# Update specific package\npoetry update package-name\n```\n\n### Virtual Environment\n\n```bash\n# Activate virtual environment\npoetry shell\n\n# Run command in virtual environment\npoetry run python script.py\n\n# Show environment info\npoetry env info\n```\n\n## 📚 Resources\n\n- [Poetry Documentation](https://python-poetry.org/docs/)\n- [Ruff Documentation](https://docs.astral.sh/ruff/)\n- [Pytest Documentation](https://docs.pytest.org/)\n- [MyPy Documentation](https://mypy.readthedocs.io/)\n- [PEP 8 Style Guide](https://pep8.org/)\n- [Type Hints (PEP 484)](https://www.python.org/dev/peps/pep-0484/)\n\n## 🤝 Contributing\n\nWhen contributing to projects using this template:\n\n1. Follow the established project structure\n2. Ensure all tests pass\n3. Maintain or improve code coverage\n4. Follow the coding standards\n5. Update documentation as needed\n\n## 📄 License\n\nThis template is available for all DatumBrain projects. For specific project licenses, check the individual repository.\n\n**Maintained by**: Engineering Team / Datum Brain\n\n**Last updated**: 2025-08-28 16:30:05\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatumbrain%2Fpython","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatumbrain%2Fpython","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatumbrain%2Fpython/lists"}