mongodb-query-builder 1.0.0__tar.gz

mongodb_query_builder-1.0.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive documentation system with Sphinx and Markdown formats
+- Getting Started guide with installation instructions
+- Complete API reference documentation for all builders
+- Tutorial: Basic Queries with exercises
+- Migration guide for converting raw MongoDB queries
+- Performance optimization guide
+- Documentation build system with `make docs` commands
+- Multiple installation methods documented (PyPI, source, GitHub)
+
+## [1.0.0] - 2025-10-03
+
+### Added
+
+#### QueryFilter
+- Fluent interface for building MongoDB queries
+- Comparison operators: equals, not_equals, greater_than, less_than, between
+- String operations: contains, starts_with, ends_with, regex
+- Array operations: array_contains, array_contains_all, array_size, elem_match
+- Logical operators: any_of, all_of, none_of, not_filter
+- Existence checks: exists, is_null, is_not_null
+- Text search support with language and sensitivity options
+- Automatic ObjectId string conversion
+- Comprehensive error handling with QueryFilterError
+
+#### AggregateBuilder
+- Fluent interface for building MongoDB aggregation pipelines
+- Pipeline stages: match, project, group, sort, limit, skip
+- Join operations: lookup, lookup_pipeline, graph_lookup
+- Array operations: unwind with preserve_null and include_array_index
+- Field manipulation: add_fields, set, unset, replace_root, replace_with
+- Faceting: facet, bucket, bucket_auto
+- Output stages: count, sort_by_count, sample, out, merge
+- Union operations: union_with
+- Advanced features: redact, custom_stage
+- Comprehensive error handling with AggregateBuilderError
+
+#### AtlasSearchBuilder
+- Fluent interface for building MongoDB Atlas Search queries
+- Search operators: text, phrase, autocomplete, wildcard, regex, range
+- Compound queries with CompoundBuilder
+- Clause types: must, should, must_not, filter
+- Minimum should match configuration
+- Faceting support with string, number, and date types
+- Facet operator mode for advanced aggregations
+- Score boosting and scoring functions
+- Count configuration (lowerBound/total)
+- More like this search
+- Build as $search or $searchMeta stages
+- Comprehensive error handling with AtlasSearchError
+
+#### Testing
+- Comprehensive test suite with 90%+ coverage
+- Tests for QueryFilter (50+ test cases)
+- Tests for AggregateBuilder (40+ test cases)
+- Tests for AtlasSearchBuilder and CompoundBuilder (30+ test cases)
+- Unit tests for all operators and methods
+- Error handling tests
+
+#### Documentation
+- Comprehensive README with examples
+- API documentation with type hints
+- Real-world usage examples
+- Contributing guidelines
+- Development setup instructions
+
+#### Project Infrastructure
+- Modern Python packaging with pyproject.toml
+- Setup.py for backward compatibility
+- GitHub Actions CI/CD workflow
+- Code quality tools: black, isort, flake8, mypy, pylint
+- Makefile for common development tasks
+- Requirements files for dependencies
+- MIT License
+- .gitignore for Python projects
+
+### Features Highlights
+
+- **Type Safety**: Full type hints throughout the codebase
+- **Validation**: Built-in validation for all operations
+- **Error Messages**: Clear, helpful error messages
+- **Chainable API**: Fluent, chainable method calls
+- **Python 3.8+**: Support for Python 3.8 through 3.12
+- **Zero Breaking Changes**: Stable API from v1.0.0
+- **Well Tested**: Comprehensive test coverage
+- **Documentation**: Extensive documentation and examples
+
+### Planned Features
+- Additional aggregation operators ($densify, $fill, etc.)
+- Enhanced Atlas Search features (geoWithin, geoShape)
+- Async/await support with motor
+- Performance optimizations for large pipelines
+- Additional tutorials (Aggregation, Atlas Search, Advanced Patterns)
+- Cookbook with real-world examples
+- Type stub files for better IDE support
+
+---
+
+[1.0.0]: https://github.com/ch-dev401/mongodb-query-builder/releases/tag/v1.0.0

mongodb_query_builder-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Company/Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mongodb_query_builder-1.0.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+include pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.py
+global-exclude *.pyc
+global-exclude __pycache__

mongodb_query_builder-1.0.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: mongodb-query-builder
+Version: 1.0.0
+Summary: A fluent, type-safe query builder for MongoDB with support for aggregations and Atlas Search
+Author-email: Christian De Asis <cdeasis923@gmail.comm>
+Maintainer-email: Christian De Asis <cdeasis923@gmail.comm>
+License: MIT
+Project-URL: Homepage, https://github.com/ch-dev401/mongodb-query-builder
+Project-URL: Documentation, https://mongodb-query-builder.readthedocs.io
+Project-URL: Repository, https://github.com/ch-dev401/mongodb-query-builder
+Project-URL: Bug Tracker, https://github.com/ch-dev401/mongodb-query-builder/issues
+Project-URL: Changelog, https://github.com/ch-dev401/mongodb-query-builder/blob/main/CHANGELOG.md
+Keywords: mongodb,query-builder,aggregation,atlas-search,database,fluent-api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mongodb
+Requires-Dist: pymongo>=4.0.0; extra == "mongodb"
+Provides-Extra: async
+Requires-Dist: motor>=3.0.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: black>=25.9.0; extra == "dev"
+Requires-Dist: flake8>=7.3.0; extra == "dev"
+Requires-Dist: isort>=6.1.0; extra == "dev"
+Requires-Dist: mypy>=1.18.2; extra == "dev"
+Requires-Dist: pre-commit>=4.3.0; extra == "dev"
+Requires-Dist: pylint>=3.3.8; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: mongomock>=4.1.0; extra == "test"
+Provides-Extra: docs
+Provides-Extra: all
+Requires-Dist: mongodb-query-builder[async,dev,docs,mongodb,test]; extra == "all"
+Dynamic: license-file
+
+# MongoDB Query Builder
+
+A fluent, type-safe query builder for MongoDB with support for complex queries, aggregation pipelines, and Atlas Search.
+
+## Features
+
+✨ **Fluent API** - Chain methods for readable query construction  
+🔒 **Type-safe** - Full type hints and validation  
+📦 **Comprehensive** - Support for queries, aggregations, and Atlas Search  
+🎯 **Intuitive** - Pythonic interface for MongoDB operations  
+✅ **Well-tested** - Extensive test coverage  
+📚 **Well-documented** - Complete API documentation and examples
+
+## Installation
+
+```bash
+pip install mongodb-query-builder
+```
+
+## Quick Start
+
+### Simple Query
+
+```python
+from mongodb_query_builder import QueryFilter
+
+# Build a query filter
+query = QueryFilter()\
+    .field("age").greater_than(18)\
+    .field("status").equals("active")\
+    .build()
+
+# Use with pymongo
+collection.find(query)
+```
+
+### Aggregation Pipeline
+
+```python
+from mongodb_query_builder import AggregateBuilder, QueryFilter
+
+# Build aggregation pipeline
+pipeline = AggregateBuilder()\
+    .match(QueryFilter().field("status").equals("active"))\
+    .group(by="$category", count={"$sum": 1}, total={"$sum": "$amount"})\
+    .sort("count", ascending=False)\
+    .limit(10)\
+    .build()
+
+# Use with pymongo
+results = collection.aggregate(pipeline)
+```
+
+### Atlas Search
+
+```python
+from mongodb_query_builder import AtlasSearchBuilder, CompoundBuilder
+
+# Simple text search
+search = AtlasSearchBuilder()\
+    .text("python developer", path=["title", "description"])\
+    .build_stage()
+
+# Complex compound search
+compound = CompoundBuilder()
+compound.must().text("python", path="skills")
+compound.should().text("senior", path="level", score=2.0)
+compound.filter().range("experience", gte=3)
+
+search = AtlasSearchBuilder()\
+    .compound(compound)\
+    .facet("departments", type="string", path="department")\
+    .build_stage()
+
+# Use in aggregation
+pipeline = [search, {"$limit": 10}]
+results = collection.aggregate(pipeline)
+```
+
+## Core Components
+
+### QueryFilter
+
+Build MongoDB query filters with a fluent interface:
+
+```python
+from mongodb_query_builder import QueryFilter
+
+# Comparison operators
+q = QueryFilter().field("age").greater_than(18)
+q = QueryFilter().field("price").between(10, 100)
+
+# String operations
+q = QueryFilter().field("name").starts_with("John")
+q = QueryFilter().field("email").contains("@example.com")
+
+# Array operations
+q = QueryFilter().field("tags").array_contains("python")
+q = QueryFilter().field("skills").array_contains_all(["python", "mongodb"])
+
+# Logical operators
+q = QueryFilter().any_of([
+    QueryFilter().field("role").equals("admin"),
+    QueryFilter().field("role").equals("moderator")
+])
+```
+
+### AggregateBuilder
+
+Build aggregation pipelines:
+
+```python
+from mongodb_query_builder import AggregateBuilder
+
+pipeline = AggregateBuilder()\
+    .match(QueryFilter().field("status").equals("active"))\
+    .group(by="$category", count={"$sum": 1})\
+    .sort("count", ascending=False)\
+    .limit(10)\
+    .project(category="$_id", count=1, _id=0)\
+    .build()
+```
+
+### AtlasSearchBuilder
+
+Build Atlas Search queries:
+
+```python
+from mongodb_query_builder import AtlasSearchBuilder, CompoundBuilder
+
+# Text search with fuzzy matching
+search = AtlasSearchBuilder()\
+    .text("search term", path="title", fuzzy={"maxEdits": 2})\
+    .build_stage()
+
+# Compound search
+compound = CompoundBuilder()
+compound.must().text("required term", path="content")
+compound.should().text("optional term", path="tags", score=2.0)
+compound.filter().range("date", gte=datetime(2024, 1, 1))
+
+search = AtlasSearchBuilder().compound(compound).build_stage()
+```
+
+## Requirements
+
+- Python 3.8+
+- pymongo (optional, for MongoDB operations)
+- typing-extensions (for Python < 3.10)
+
+## Documentation
+
+### 📚 Getting Started
+- [Installation & Quick Start](docs/markdown/getting-started.md)
+- [Basic Queries Tutorial](docs/markdown/tutorials/01-basic-queries.md)
+
+### 🔧 API Reference
+- [QueryFilter API](docs/markdown/api/query-filter.md) - Query building methods
+- [AggregateBuilder API](docs/markdown/api/aggregate-builder.md) - Aggregation pipeline methods
+- [AtlasSearchBuilder API](docs/markdown/api/atlas-search-builder.md) - Atlas Search methods
+
+### 📖 Guides
+- [Migration Guide](docs/markdown/migration-guide.md) - Convert from raw MongoDB queries
+- [Performance Guide](docs/markdown/performance-guide.md) - Optimization best practices
+
+### 🛠️ Development
+- [Contributing Guidelines](CONTRIBUTING.md)
+
+### 📐 Full Documentation
+- [Documentation Overview](docs/markdown/README.md) - Complete documentation index
+- Online documentation available at: *(coming soon)*
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.
+
+## Support
+
+- GitHub Issues: [Report bugs or request features](https://github.com/ch-dev401/mongodb-query-builder/issues)
+- Documentation: [Full documentation](https://github.com/ch-dev401/mongodb-query-builder)

mongodb_query_builder-1.0.0/README.md

@@ -0,0 +1,184 @@
+# MongoDB Query Builder
+
+A fluent, type-safe query builder for MongoDB with support for complex queries, aggregation pipelines, and Atlas Search.
+
+## Features
+
+✨ **Fluent API** - Chain methods for readable query construction  
+🔒 **Type-safe** - Full type hints and validation  
+📦 **Comprehensive** - Support for queries, aggregations, and Atlas Search  
+🎯 **Intuitive** - Pythonic interface for MongoDB operations  
+✅ **Well-tested** - Extensive test coverage  
+📚 **Well-documented** - Complete API documentation and examples
+
+## Installation
+
+```bash
+pip install mongodb-query-builder
+```
+
+## Quick Start
+
+### Simple Query
+
+```python
+from mongodb_query_builder import QueryFilter
+
+# Build a query filter
+query = QueryFilter()\
+    .field("age").greater_than(18)\
+    .field("status").equals("active")\
+    .build()
+
+# Use with pymongo
+collection.find(query)
+```
+
+### Aggregation Pipeline
+
+```python
+from mongodb_query_builder import AggregateBuilder, QueryFilter
+
+# Build aggregation pipeline
+pipeline = AggregateBuilder()\
+    .match(QueryFilter().field("status").equals("active"))\
+    .group(by="$category", count={"$sum": 1}, total={"$sum": "$amount"})\
+    .sort("count", ascending=False)\
+    .limit(10)\
+    .build()
+
+# Use with pymongo
+results = collection.aggregate(pipeline)
+```
+
+### Atlas Search
+
+```python
+from mongodb_query_builder import AtlasSearchBuilder, CompoundBuilder
+
+# Simple text search
+search = AtlasSearchBuilder()\
+    .text("python developer", path=["title", "description"])\
+    .build_stage()
+
+# Complex compound search
+compound = CompoundBuilder()
+compound.must().text("python", path="skills")
+compound.should().text("senior", path="level", score=2.0)
+compound.filter().range("experience", gte=3)
+
+search = AtlasSearchBuilder()\
+    .compound(compound)\
+    .facet("departments", type="string", path="department")\
+    .build_stage()
+
+# Use in aggregation
+pipeline = [search, {"$limit": 10}]
+results = collection.aggregate(pipeline)
+```
+
+## Core Components
+
+### QueryFilter
+
+Build MongoDB query filters with a fluent interface:
+
+```python
+from mongodb_query_builder import QueryFilter
+
+# Comparison operators
+q = QueryFilter().field("age").greater_than(18)
+q = QueryFilter().field("price").between(10, 100)
+
+# String operations
+q = QueryFilter().field("name").starts_with("John")
+q = QueryFilter().field("email").contains("@example.com")
+
+# Array operations
+q = QueryFilter().field("tags").array_contains("python")
+q = QueryFilter().field("skills").array_contains_all(["python", "mongodb"])
+
+# Logical operators
+q = QueryFilter().any_of([
+    QueryFilter().field("role").equals("admin"),
+    QueryFilter().field("role").equals("moderator")
+])
+```
+
+### AggregateBuilder
+
+Build aggregation pipelines:
+
+```python
+from mongodb_query_builder import AggregateBuilder
+
+pipeline = AggregateBuilder()\
+    .match(QueryFilter().field("status").equals("active"))\
+    .group(by="$category", count={"$sum": 1})\
+    .sort("count", ascending=False)\
+    .limit(10)\
+    .project(category="$_id", count=1, _id=0)\
+    .build()
+```
+
+### AtlasSearchBuilder
+
+Build Atlas Search queries:
+
+```python
+from mongodb_query_builder import AtlasSearchBuilder, CompoundBuilder
+
+# Text search with fuzzy matching
+search = AtlasSearchBuilder()\
+    .text("search term", path="title", fuzzy={"maxEdits": 2})\
+    .build_stage()
+
+# Compound search
+compound = CompoundBuilder()
+compound.must().text("required term", path="content")
+compound.should().text("optional term", path="tags", score=2.0)
+compound.filter().range("date", gte=datetime(2024, 1, 1))
+
+search = AtlasSearchBuilder().compound(compound).build_stage()
+```
+
+## Requirements
+
+- Python 3.8+
+- pymongo (optional, for MongoDB operations)
+- typing-extensions (for Python < 3.10)
+
+## Documentation
+
+### 📚 Getting Started
+- [Installation & Quick Start](docs/markdown/getting-started.md)
+- [Basic Queries Tutorial](docs/markdown/tutorials/01-basic-queries.md)
+
+### 🔧 API Reference
+- [QueryFilter API](docs/markdown/api/query-filter.md) - Query building methods
+- [AggregateBuilder API](docs/markdown/api/aggregate-builder.md) - Aggregation pipeline methods
+- [AtlasSearchBuilder API](docs/markdown/api/atlas-search-builder.md) - Atlas Search methods
+
+### 📖 Guides
+- [Migration Guide](docs/markdown/migration-guide.md) - Convert from raw MongoDB queries
+- [Performance Guide](docs/markdown/performance-guide.md) - Optimization best practices
+
+### 🛠️ Development
+- [Contributing Guidelines](CONTRIBUTING.md)
+
+### 📐 Full Documentation
+- [Documentation Overview](docs/markdown/README.md) - Complete documentation index
+- Online documentation available at: *(coming soon)*
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.
+
+## Support
+
+- GitHub Issues: [Report bugs or request features](https://github.com/ch-dev401/mongodb-query-builder/issues)
+- Documentation: [Full documentation](https://github.com/ch-dev401/mongodb-query-builder)

mongodb_query_builder-1.0.0/docs/markdown/README.md

@@ -0,0 +1,89 @@
+# MongoDB Query Builder Documentation
+
+Welcome to the MongoDB Query Builder documentation! This library provides a fluent, type-safe interface for constructing MongoDB queries, aggregation pipelines, and Atlas Search operations.
+
+## 📚 Documentation Overview
+
+### Getting Started
+- [Installation & Quick Start](getting-started.md) - How to install and get started with MongoDB Query Builder
+- Basic Concepts - Understanding QueryFilter, AggregateBuilder, and AtlasSearchBuilder
+
+### Tutorials
+Step-by-step guides for learning the library:
+
+1. [Basic Queries](tutorials/01-basic-queries.md) - Simple queries and filters ✅
+2. Aggregation Pipelines *(coming soon)* - Building complex data pipelines
+3. Atlas Search *(coming soon)* - Full-text search with Atlas
+4. Advanced Patterns *(coming soon)* - Complex query patterns and optimization
+
+### API Reference
+Detailed documentation for all components:
+
+- [QueryFilter](api/query-filter.md) - Building MongoDB query filters ✅
+- [AggregateBuilder](api/aggregate-builder.md) - Constructing aggregation pipelines ✅
+- [AtlasSearchBuilder](api/atlas-search-builder.md) - Atlas Search queries ✅
+
+### Guides
+- [Migration Guide](migration-guide.md) - Converting raw MongoDB queries ✅
+- [Performance Guide](performance-guide.md) - Query optimization tips ✅
+
+### Cookbook *(coming soon)*
+Real-world examples and patterns:
+
+- User Authentication - User login and permission queries
+- Product Catalog - E-commerce search and filtering
+- Analytics Pipeline - Data aggregation for analytics
+- Time Series - Working with time-series data
+
+## 🚀 Quick Example
+
+```python
+from mongodb_query_builder import QueryFilter, AggregateBuilder
+
+# Simple query
+query = QueryFilter()
+    .field("age").greater_than(18)
+    .field("status").equals("active")
+    .build()
+
+# Aggregation pipeline
+pipeline = AggregateBuilder()
+    .match(QueryFilter().field("status").equals("active"))
+    .group(by="$category", count={"$sum": 1})
+    .sort("count", ascending=False)
+    .limit(10)
+    .build()
+```
+
+## 🔍 Finding What You Need
+
+- **New to MongoDB Query Builder?** Start with the [Getting Started Guide](getting-started.md)
+- **Looking for specific functionality?** Check the [API Reference](#api-reference)
+- **Need examples?** Browse the [Cookbook](#cookbook) *(coming soon)*
+- **Having issues?** Check our [GitHub Issues](https://github.com/ch-dev401/mongodb-query-builder/issues)
+
+## 📖 Documentation Versions
+
+This documentation is available in two formats:
+
+1. **Markdown Documentation** (this version) - GitHub-friendly, easy to browse
+2. **Sphinx Documentation** - Full API documentation with search functionality
+
+## 🤝 Contributing
+
+We welcome contributions! See our [Contributing Guide](../../CONTRIBUTING.md) for details on:
+- Reporting issues
+- Suggesting features
+- Submitting pull requests
+- Documentation improvements
+
+## 📄 License
+
+MongoDB Query Builder is released under the MIT License. See the [LICENSE](../../LICENSE) file for details.
+
+---
+
+**Need help?** 
+- 📧 Open an issue on [GitHub](https://github.com/ch-dev401/mongodb-query-builder/issues)
+- 💬 Join our [community discussions](https://github.com/ch-dev401/mongodb-query-builder/discussions)
+- 📚 Read the [documentation](getting-started.md)