django-smart-ratelimit 0.1.0__tar.gz

django_smart_ratelimit-0.1.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+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/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# 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
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .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
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.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/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
+#  project, it is recommended to ignore .idea/ directory.
+.idea/
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Linux
+*~
+
+# Project specific
+test_db.sqlite3
+*.db
+*.sqlite
+*.sqlite3
+
+# Backup files
+*.bak
+*.backup
+*.old
+*.orig
+
+# Temporary files
+*.tmp
+*.temp
+.tmp/
+.temp/
+
+# Log files
+*.log
+*.out
+*.err
+
+# Redis dump
+dump.rdb
+
+# Coverage reports
+htmlcov/
+coverage/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Documentation builds
+docs/_build/
+docs/build/
+site/

django_smart_ratelimit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yasser Shkeir
+
+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.

django_smart_ratelimit-0.1.0/PKG-INFO

@@ -0,0 +1,402 @@
+Metadata-Version: 2.4
+Name: django-smart-ratelimit
+Version: 0.1.0
+Summary: A flexible and efficient rate limiting library for Django applications
+Project-URL: Homepage, https://github.com/YasserShkeir/django-smart-ratelimit
+Project-URL: Documentation, https://django-smart-ratelimit.readthedocs.io
+Project-URL: Repository, https://github.com/YasserShkeir/django-smart-ratelimit
+Project-URL: Issues, https://github.com/YasserShkeir/django-smart-ratelimit/issues
+Project-URL: Changelog, https://github.com/YasserShkeir/django-smart-ratelimit/blob/main/CHANGELOG.md
+Author-email: Yasser Shkeir <shkeiryasser@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: decorator,django,middleware,rate-limiting,redis
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: django>=3.2
+Requires-Dist: redis>=4.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: black>=22.0; extra == 'dev'
+Requires-Dist: build>=0.8; extra == 'dev'
+Requires-Dist: django-stubs>=4.0; extra == 'dev'
+Requires-Dist: flake8-docstrings>=1.7; extra == 'dev'
+Requires-Dist: flake8>=5.0; extra == 'dev'
+Requires-Dist: isort>=5.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pre-commit>=2.20; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-django>=4.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: safety>=2.0; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Requires-Dist: types-redis>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Django Smart Ratelimit
+
+[![CI](https://github.com/YasserShkeir/django-smart-ratelimit/workflows/CI/badge.svg)](https://github.com/YasserShkeir/django-smart-ratelimit/actions)
+[![PyPI version](https://badge.fury.io/py/django-smart-ratelimit.svg)](https://badge.fury.io/py/django-smart-ratelimit)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-smart-ratelimit.svg)](https://pypi.org/project/django-smart-ratelimit/)
+[![Django versions](https://img.shields.io/pypi/djversions/django-smart-ratelimit.svg)](https://pypi.org/project/django-smart-ratelimit/)
+
+A flexible and efficient rate limiting library for Django applications with support for multiple backends and sliding window algorithms.
+
+## Features
+
+- 🚀 **High Performance**: Atomic operations using Redis Lua scripts
+- 🔧 **Flexible Configuration**: Both decorator and middleware support
+- 🪟 **Multiple Algorithms**: Fixed window and sliding window rate limiting
+- 🔌 **Multiple Backends**: Redis backend with extensible architecture
+- 📊 **Rich Headers**: Standard rate limiting headers
+- 🛡️ **Production Ready**: Comprehensive testing and error handling
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install django-smart-ratelimit
+```
+
+### Basic Usage
+
+#### Decorator Style
+
+```python
+from django_smart_ratelimit import rate_limit
+
+@rate_limit(key='ip', rate='10/m')
+def my_view(request):
+    return HttpResponse('Hello World')
+
+@rate_limit(key='user:{user.id}', rate='100/h', block=True)
+def api_endpoint(request):
+    return JsonResponse({'data': 'some data'})
+```
+
+#### Middleware Style
+
+```python
+# settings.py
+MIDDLEWARE = [
+    'django_smart_ratelimit.middleware.RateLimitMiddleware',
+    # ... other middleware
+]
+
+RATELIMIT_MIDDLEWARE = {
+    'DEFAULT_RATE': '100/m',
+    'BACKEND': 'redis',
+    'SKIP_PATHS': ['/admin/', '/health/'],
+    'RATE_LIMITS': {
+        '/api/': '1000/h',
+        '/auth/login/': '5/m',
+    }
+}
+```
+
+### Configuration
+
+#### Redis Backend
+
+```python
+# settings.py
+RATELIMIT_BACKEND = 'redis'
+RATELIMIT_REDIS = {
+    'host': 'localhost',
+    'port': 6379,
+    'db': 0,
+    'password': None,
+}
+
+# Algorithm selection
+RATELIMIT_USE_SLIDING_WINDOW = True  # or False for fixed window
+```
+
+## Usage Examples
+
+### Decorator Examples
+
+#### Basic Rate Limiting
+
+```python
+from django_smart_ratelimit import rate_limit
+
+# Limit by IP address
+@rate_limit(key='ip', rate='10/m')
+def public_api(request):
+    return JsonResponse({'message': 'Hello World'})
+
+# Limit by user
+@rate_limit(key='user', rate='100/h')
+def user_api(request):
+    return JsonResponse({'user_data': '...'})
+```
+
+#### Custom Key Functions
+
+```python
+def custom_key(request):
+    if request.user.is_authenticated:
+        return f"user:{request.user.id}"
+    return f"ip:{request.META.get('REMOTE_ADDR')}"
+
+@rate_limit(key=custom_key, rate='50/m')
+def smart_api(request):
+    return JsonResponse({'data': '...'})
+```
+
+#### Non-blocking Rate Limiting
+
+```python
+@rate_limit(key='ip', rate='10/m', block=False)
+def api_with_headers(request):
+    # This will add headers but not block requests
+    return JsonResponse({'data': '...'})
+```
+
+### Middleware Examples
+
+#### Path-based Rate Limiting
+
+```python
+RATELIMIT_MIDDLEWARE = {
+    'DEFAULT_RATE': '100/m',
+    'RATE_LIMITS': {
+        '/api/public/': '1000/h',
+        '/api/private/': '100/h',
+        '/auth/': '5/m',
+        '/upload/': '10/h',
+    }
+}
+```
+
+#### Custom Key Functions
+
+```python
+# utils.py
+def user_key_function(request):
+    if request.user.is_authenticated:
+        return f"user:{request.user.id}"
+    return f"ip:{request.META.get('REMOTE_ADDR')}"
+
+def api_key_function(request):
+    api_key = request.META.get('HTTP_X_API_KEY')
+    if api_key:
+        return f"api_key:{api_key}"
+    return f"ip:{request.META.get('REMOTE_ADDR')}"
+
+# settings.py
+RATELIMIT_MIDDLEWARE = {
+    'KEY_FUNCTION': 'myapp.utils.user_key_function',
+    'RATE_LIMITS': {
+        '/api/': '1000/h',
+    }
+}
+```
+
+## Rate Formats
+
+The library supports several rate formats:
+
+- `10/s` - 10 requests per second
+- `100/m` - 100 requests per minute
+- `1000/h` - 1000 requests per hour
+- `10000/d` - 10000 requests per day
+
+## Response Headers
+
+When rate limiting is applied, the following headers are added:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 75
+X-RateLimit-Reset: 1640995200
+```
+
+## Algorithms
+
+### Fixed Window
+
+Simple and memory-efficient algorithm that resets the counter at fixed intervals.
+
+**Pros:**
+
+- Low memory usage
+- Simple implementation
+- Predictable reset times
+
+**Cons:**
+
+- Potential for burst traffic
+- Less accurate limiting
+
+### Sliding Window
+
+More accurate algorithm that maintains a sliding window of requests.
+
+**Pros:**
+
+- Accurate rate limiting
+- No burst traffic issues
+- Smooth rate limiting
+
+**Cons:**
+
+- Higher memory usage
+- More complex implementation
+
+## Configuration Reference
+
+### Decorator Parameters
+
+| Parameter | Type                | Default  | Description                           |
+| --------- | ------------------- | -------- | ------------------------------------- |
+| `key`     | `str` or `callable` | Required | Rate limit key or key function        |
+| `rate`    | `str`               | Required | Rate limit (e.g., '10/m')             |
+| `block`   | `bool`              | `True`   | Block requests when limit exceeded    |
+| `backend` | `str`               | `None`   | Backend to use (uses default if None) |
+
+### Middleware Settings
+
+| Setting        | Type   | Default   | Description                        |
+| -------------- | ------ | --------- | ---------------------------------- |
+| `DEFAULT_RATE` | `str`  | `'100/m'` | Default rate limit                 |
+| `BACKEND`      | `str`  | `'redis'` | Backend to use                     |
+| `KEY_FUNCTION` | `str`  | `None`    | Import path to key function        |
+| `BLOCK`        | `bool` | `True`    | Block requests when limit exceeded |
+| `SKIP_PATHS`   | `list` | `[]`      | Paths to skip rate limiting        |
+| `RATE_LIMITS`  | `dict` | `{}`      | Path-specific rate limits          |
+
+### Backend Settings
+
+| Setting                        | Type   | Default        | Description                  |
+| ------------------------------ | ------ | -------------- | ---------------------------- |
+| `RATELIMIT_BACKEND`            | `str`  | `'redis'`      | Backend to use               |
+| `RATELIMIT_REDIS`              | `dict` | `{}`           | Redis configuration          |
+| `RATELIMIT_USE_SLIDING_WINDOW` | `bool` | `True`         | Use sliding window algorithm |
+| `RATELIMIT_KEY_PREFIX`         | `str`  | `'ratelimit:'` | Redis key prefix             |
+
+## Development
+
+### Running Tests
+
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=django_smart_ratelimit --cov-report=html
+
+# Run specific test file
+pytest tests/test_decorator.py
+```
+
+### Code Quality
+
+```bash
+# Format code
+black django_smart_ratelimit tests
+
+# Check linting
+flake8 django_smart_ratelimit tests
+
+# Type checking
+mypy django_smart_ratelimit
+```
+
+### Pre-commit Hooks
+
+```bash
+# Install pre-commit hooks
+pre-commit install
+
+# Run hooks manually
+pre-commit run --all-files
+```
+
+## Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Run the test suite (`pytest`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### Contribution Guidelines
+
+- Write tests for new features
+- Follow the existing code style
+- Add docstrings to new functions and classes
+- Update documentation as needed
+- Add type hints where appropriate
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### v0.1.0 (Initial Release)
+
+- Basic decorator and middleware support
+- Redis backend with sliding window algorithm
+- Comprehensive test suite
+- Documentation and examples
+
+## Support
+
+- 📖 [Documentation](docs/design.md)
+- 🐛 [Issue Tracker](https://github.com/YasserShkeir/django-smart-ratelimit/issues)
+- 💬 [Discussions](https://github.com/YasserShkeir/django-smart-ratelimit/discussions)
+
+## 💖 Support the Project
+
+If this library has saved you time and effort, consider supporting its development:
+
+### Cryptocurrency Donations
+
+- **USDT (Ethereum)**: `0x202943b3a6CC168F92871d9e295537E6cbc53Ff4`
+
+### Alternative Support Methods
+
+- ⭐ **Star this repository** on GitHub
+- 🐛 **Report bugs** and suggest features
+- 🔀 **Contribute** code improvements
+- 📢 **Share** with your team and community
+
+Your support helps maintain and improve this open-source project! 🙏
+
+## Acknowledgments
+
+- Created by Yasser Shkeir
+- Inspired by existing Django rate limiting libraries
+- Thanks to the Django and Redis communities
+- Special thanks to all contributors