mongo-aggro 0.1.0__tar.gz → 0.2.2__tar.gz

mongo_aggro-0.2.2/.codespellrc

@@ -0,0 +1,3 @@
+[codespell]
+skip = *.json,*.lock,*.min.js,.git,__pycache__,.mypy_cache,.pytest_cache,.venv,venv
+ignore-words-list = BottomN,Nin,bottomN,nin

mongo_aggro-0.2.2/.github/instructions/commit-style.instructions.md

@@ -0,0 +1,3 @@
+# Commit Style Guidance
+
+All commit messages must use the prescribed types (`feat`, `ref`, `doc`, `ci`, `cd`, `dep`, `style`, `fix`) and follow Conventional Commits. The first line must describe all actions in ≤50 characters, be a single sentence that explains everything that changed, and be followed by an empty line and detail lines that start with `-` describing each change. If referencing a specific Sentry or GitHub issue with a unique code, include it as `(type #code: ...)`, e.g., `(fix #gh45: use x instead of y)`.

mongo_aggro-0.2.2/.github/instructions/python-coding.instructions.md

@@ -0,0 +1,7 @@
+# Python Coding Guidance
+
+1. Simplicity always wins—write readable, clean Python that adheres to PEP 8, as though Black and isort already ran. Wrap or break any docstring, comment, or f-string exceeding 79 characters into multiple lines.
+2. Determine the highest Python version used in this repo, prefer that (or specify it if multiple versions exist), and leverage its modern type hints extensively. Favor typing tools (TypeVar, generics, Literal, etc.) or Pydantic models when available; avoid magic literals by defining named constants.
+3. Prefer functional programming over OOP whenever feasible, defaulting to enums (IntEnum, StrEnum, etc.) over mappings and selecting the enum variant that matches the data. Keep every line ≤79 characters.
+4. Detect and use the repo’s package manager—prefer `uv`, then `poetry`, then `pipenv`, then `pip`—and always rely on existing Makefile targets instead of inventing new commands when a Makefile exists.
+5. Never use unparameterized collection types; always annotate what items they hold (e.g., `list[str]`, `dict[str, int | str]`). If the item types vary or are unknown, use `Any` (after importing it from `typing`) so the collection remains precise (e.g., `dict[str, Any]`).

mongo_aggro-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra test
+
+      - name: Run tests
+        run: uv run pytest -v --cov=mongo_aggro --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mongo_aggro-0.2.2/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

mongo_aggro-0.2.2/.gitignore

@@ -0,0 +1,143 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+!**/__pycache__/
+*.py[cod]
+*$py.class
+app/__pycache__/
+media/
+web_app/
+dash_app/
+.sourcery.yaml
+# C extensions
+*.so
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+database/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+junit.xml
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+.vscode/
+media/
+.idea/
+.env
+./app/utils/Faker.py
+poetry.toml
+docker/
+site/

mongo_aggro-0.2.2/.pre-commit-config.yaml

@@ -0,0 +1,53 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-toml
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        args: ["--config", ".codespellrc"]
+
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.19.0
+    hooks:
+      - id: pyupgrade
+        args: ["--py312-plus"]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - mypy-extensions==1.0.0
+          - pydantic>=2.10.0
+          - types-requests
+
+  - repo: https://github.com/python-poetry/poetry
+    rev: 2.0.1
+    hooks:
+      - id: poetry-check

mongo_aggro-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to Mongo Aggro
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://github.com/astral-sh/uv) for package management
+
+### Setup
+
+```bash
+git clone https://github.com/hamedghenaat/mongo-aggro.git
+cd mongo-aggro
+
+# Install dependencies
+uv sync --all-extras
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## Development Workflow
+
+```bash
+# Run tests
+make test
+
+# Run linter
+make lint
+
+# Format code
+make format
+
+# Run all checks
+make check
+```
+
+## Code Style
+
+- **Ruff** for linting and formatting
+- **79 character** line limit
+- **Type hints** required on all functions
+- **Google-style** docstrings
+
+### Example
+
+```python
+def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+    """
+    Convert stage to MongoDB dictionary.
+
+    Args:
+        **kwargs: Additional Pydantic arguments.
+
+    Returns:
+        MongoDB aggregation stage dictionary.
+
+    Example:
+        >>> Match(query={"status": "active"}).model_dump()
+        {"$match": {"status": "active"}}
+    """
+    return {"$match": self.query}
+```
+
+## Adding Features
+
+### New Stage
+
+1. Add class in `mongo_aggro/stages.py`
+2. Export in `mongo_aggro/__init__.py`
+3. Add tests in `tests/test_stages.py`
+4. Update documentation
+
+### New Expression
+
+1. Add class in `mongo_aggro/expressions.py`
+2. Export in `mongo_aggro/__init__.py`
+3. Add tests in `tests/test_expressions.py`
+
+## Commit Style
+
+Use conventional commits:
+- `feat:` New features
+- `fix:` Bug fixes
+- `doc:` Documentation
+- `ref:` Refactoring
+- `ci:` CI/CD changes
+
+```bash
+git commit -m "feat: add new stage
+
+- Add NewStage class
+- Add tests
+- Update documentation"
+```
+
+## Pull Request Process
+
+1. Create feature branch
+2. Make changes with tests
+3. Run `make check`
+4. Push and create PR
+5. Address review comments
+
+## Questions?
+
+Open an issue for any questions.

mongo_aggro-0.2.2/Makefile

@@ -0,0 +1,83 @@
+.PHONY: help install install-dev install-test install-all lint format test test-cov clean build publish docs docs-serve
+
+PYTHON := python
+UV := uv
+
+help:  ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install production dependencies
+	$(UV) sync --no-dev
+
+install-dev:  ## Install development dependencies
+	$(UV) sync --extra dev
+
+install-test:  ## Install test dependencies
+	$(UV) sync --extra test
+
+install-all:  ## Install all dependencies (dev + test + docs)
+	$(UV) sync --extra dev --extra test --extra docs
+
+lint:  ## Run all linters
+	$(UV) run ruff check .
+	$(UV) run mypy mongo_aggro
+
+format:  ## Format code with black and isort
+	$(UV) run black .
+	$(UV) run isort .
+	$(UV) run ruff check --fix .
+
+test:  ## Run tests
+	$(UV) run pytest
+
+test-cov:  ## Run tests with coverage
+	$(UV) run pytest --cov=mongo_aggro --cov-report=term-missing --cov-report=html
+
+test-fast:  ## Run tests without coverage (faster)
+	$(UV) run pytest -x -q
+
+pre-commit:  ## Run pre-commit hooks on all files
+	$(UV) run pre-commit run --all-files
+
+pre-commit-install:  ## Install pre-commit hooks
+	$(UV) run pre-commit install
+
+clean:  ## Clean build artifacts
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info/
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	rm -rf .ruff_cache/
+	rm -rf htmlcov/
+	rm -rf .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+
+build:  ## Build package
+	$(UV) build
+
+publish:  ## Publish to PyPI (usage: make publish REPO=pypi)
+	$(UV) run twine upload --repository $(REPO) dist/*
+
+publish-test:  ## Publish to TestPyPI
+	$(UV) run twine upload --repository testpypi dist/*
+
+check:  ## Run all checks (lint + test)
+	$(MAKE) lint
+	$(MAKE) test
+
+ci:  ## Run CI pipeline (format check + lint + test)
+	$(UV) run black --check .
+	$(UV) run isort --check-only .
+	$(MAKE) lint
+	$(MAKE) test-cov
+
+docs:  ## Build documentation
+	$(UV) run mkdocs build
+
+docs-serve:  ## Serve documentation locally
+	$(UV) run mkdocs serve
+
+docs-deploy:  ## Deploy documentation to GitHub Pages
+	$(UV) run mkdocs gh-deploy --force