Preparation for stable release

.github/workflows/checks.yml

@@ -13,9 +13,8 @@ jobs:
           - "3.10"
           - "3.11"
           - "3.12"
+          - "3.13"
         django-version:
-          - ">=4.0,<4.1"
-          - ">=4.1,<4.2"
           - ">=4.2,<4.3"
           - ">=5.0,<5.2"
     name: Python ${{ matrix.python-version }} - Django ${{ matrix.django-version }}

.gitignore

@@ -113,3 +113,6 @@ test_project/db.sqlite3
 
 # Database dumps
 *.sql
+
+# MacOS files
+.DS_Store

CONTRIBUTING.rst

@@ -15,11 +15,10 @@ Types of Contributions
 Report Bugs
 ~~~~~~~~~~~
 
-Report bugs at https://github.com/saritasa-nest/django-import-export-extensions.
+Report bugs at https://github.com/saritasa-nest/django-import-export-extensions/issues.
 
 If you are reporting a bug, please include:
 
-* Your operating system name and version.
 * Any details about your local setup that might be helpful in troubleshooting.
 * Detailed steps to reproduce the bug.
 
@@ -38,14 +37,14 @@ and "help wanted" is open to whoever wants to implement it.
 Write Documentation
 ~~~~~~~~~~~~~~~~~~~
 
-django-import-export-extensions could always use more documentation, whether as part of the
-official django-import-export-extensions docs, in docstrings, or even on the web in blog posts,
+``django-import-export-extensions`` could always use more documentation, whether as part of the
+official ``django-import-export-extensions`` docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
 Submit Feedback
 ~~~~~~~~~~~~~~~
 
-The best way to send feedback is to file an issue at https://github.com/saritasa-nest/django-import-export-extensions.
+The best way to send feedback is to file an issue at https://github.com/saritasa-nest/django-import-export-extensions/issues.
 
 If you are proposing a feature:
 
@@ -62,31 +61,39 @@ Ready to contribute? Here's how to set up `django-import-export-extensions` for
 1. Fork the `django-import-export-extensions` repo on GitHub.
 2. Clone your fork locally::
 
-    $ git clone [email protected]:your_name_here/django-import-export-extensions.git
+    git clone [email protected]:your_name_here/django-import-export-extensions.git
 
-3. Setup virtual environment using pyenv::
+3. Setup virtual environment:
 
-    $ pyenv install 3.11
-    $ pyenv shell $(pyenv latest 3.11)
-    $ poetry config virtualenvs.in-project true
-    $ poetry env use $(which python) &&  poetry install && source .venv/bin/activate
+  Using pyenv::
+
+    pyenv install 3.12
+    pyenv shell $(pyenv latest 3.12)
+    poetry config virtualenvs.in-project true
+    source .venv/bin/activate && poetry install
+
+  Using uv::
+
+    uv venv --python 3.12 --prompt django-import-export-extensions --seed
+    poetry config virtualenvs.in-project true
+    source .venv/bin/activate && poetry install
 
 4. Create a branch for local development::
 
-    $ git checkout -b name-of-your-bugfix-or-feature
+    git checkout -b name-of-your-bugfix-or-feature
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass flake8 and the
+5. When you're done making changes, check that your changes pass linters and the
    tests::
 
-    $ inv pre-commit.run-hooks
+    inv pre-commit.run-hooks
 
 6. Commit your changes and push your branch to GitHub::
 
-    $ git add .
-    $ git commit -m "Your detailed description of your changes."
-    $ git push origin name-of-your-bugfix-or-feature
+    git add .
+    git commit -m "Your detailed description of your changes."
+    git push origin name-of-your-bugfix-or-feature
 
 7. Submit a pull request through the GitHub website.
 
@@ -98,13 +105,6 @@ Before you submit a pull request, check that it meets these guidelines:
 1. The pull request should include tests.
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
-3. The pull request should work for Python 3.10, 3.11, and for PyPy. Check
-   github actions status, verify that all checks have been passed
-
-Tips
-----
-
-To run a subset of tests::
-
-    $ pytest tests.test_api
+   feature to the list in README.md.
+3. The pull request should work for each supported Python version, and for PyPy. Check
+   github actions status, verify that all checks have been passed.

HISTORY.rst

@@ -5,6 +5,8 @@ History
 UNRELEASED
 ----------
 * Replaced `sphinx-rtd-theme` by [furo](https://github.com/pradyunsg/furo)
+* Update/extend documentation
+* Support Python 3.13
 
 0.7.0 (2024-10-29)
 ------------------

README.md

@@ -0,0 +1,118 @@
+# Django-import-export-extensions
+
+| Project   |     | Status |
+|-----------|:----|--------|
+| Versions  |     | [![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/django-import-export-extensions)](https://pypi.org/project/django-import-export-extensions/)<br>[![PyPI - Django Versions](https://img.shields.io/pypi/frameworkversions/django/django-import-export-extensions)](https://pypi.org/project/django-import-export-extensions/) |
+| CI/CD     |     | [![Build status on Github](https://github.com/saritasa-nest/django-import-export-extensions/actions/workflows/checks.yml/badge.svg)](https://github.com/saritasa-nest/django-import-export-extensions/actions/workflows/checks.yml)<br>[![Test coverage](https://coveralls.io/repos/github/saritasa-nest/django-import-export-extensions/badge.svg?branch=main)](https://coveralls.io/github/saritasa-nest/django-import-export-extensions?branch=main)<br>[![Documentation Status](https://readthedocs.org/projects/django-import-export-extensions/badge/?version=latest)](https://django-import-export-extensions.readthedocs.io/en/latest/?badge=latest) |
+| Statistic |     | ![PyPI Downloads](https://static.pepy.tech/badge/django-import-export-extensions/month) |
+
+## Description
+
+`django-import-export-extensions` extends the functionality of
+[django-import-export](https://github.com/django-import-export/django-import-export/)
+adding the following features:
+
+- Import/export resources in the background via Celery
+- Manage import/export jobs via Django Admin
+- DRF integration that allows to work with import/export jobs via API
+- Support
+    [drf-spectacular](https://github.com/tfranzel/drf-spectacular)
+    generated API schema
+- Additional fields and widgets (FileWidget,
+    IntermediateManyToManyWidget, IntermediateManyToManyField)
+
+## Installation
+
+To install `django-import-export-extensions`, run this command in your
+terminal:
+
+```sh
+pip install django-import-export-extensions
+```
+
+Add `import_export` and `import_export_extensions` to `INSTALLED_APPS`
+
+```python
+# settings.py
+INSTALLED_APPS = (
+    ...,
+    "import_export",
+    "import_export_extensions",
+)
+```
+
+Run `migrate` command to create ImportJob/ExportJob models and
+`collectstatic` to let Django collect package static files to use in the
+admin.
+
+```sh
+python manage.py migrate
+python manage.py collectstatic
+```
+
+## Usage
+
+Prepare resource for your model
+
+```python
+# apps/books/resources.py
+from import_export_extensions.resources import CeleryModelResource
+
+from .. import models
+
+
+class BookResource(CeleryModelResource):
+
+    class Meta:
+        model = models.Book
+```
+
+Use `CeleryImportExportMixin` class and set `resource_classes` in admin
+model to import/export via Django Admin
+
+```python
+# apps/books/admin.py
+from django.contrib import admin
+
+from import_export_extensions.admin import CeleryImportExportMixin
+
+from .. import resources
+
+
+@admin.register(models.Book)
+class BookAdmin(CeleryImportExportMixin, admin.ModelAdmin):
+    resource_class = resources.BookResource
+```
+
+Prepare view sets to import/export via API
+
+``` python
+# apps/books/api/views.py
+from .. import resources
+
+from import_export_extensions.api import views
+
+
+class BookExportViewSet(views.ExportJobViewSet):
+    resource_class = resources.BookResource
+
+
+class BookImportViewSet(views.ImportJobViewSet):
+    resource_class = resources.BookResource
+```
+
+Don\'t forget to [configure
+Celery](https://docs.celeryq.dev/en/stable/django/first-steps-with-django.html)
+if you want to run import/export in background
+
+## Links
+
+- Documentation:
+    <https://django-import-export-extensions.readthedocs.io>.
+- GitHub:
+    <https://github.com/saritasa-nest/django-import-export-extensions/>
+- PyPI: <https://pypi.org/project/django-import-export-extensions/>
+
+## License
+
+- Free software: MIT license