From 714c702a12cceb00d64f282df7dfdac5ab747d62 Mon Sep 17 00:00:00 2001 From: Brian Kohan Date: Sat, 23 Aug 2025 15:07:51 -0700 Subject: [PATCH] rename CI workflow to Lint, move all rst repo level doc files (like README) to markdown --- .github/workflows/{ci.yml => lint.yml} | 2 +- AUTHORS.rst => AUTHORS.md | 20 +++--- CONTRIBUTING.md | 51 +++++++++++++ CONTRIBUTING.rst | 5 -- README.md | 82 +++++++++++++++++++++ README.rst | 99 -------------------------- pyproject.toml | 4 +- 7 files changed, 144 insertions(+), 119 deletions(-) rename .github/workflows/{ci.yml => lint.yml} (96%) rename AUTHORS.rst => AUTHORS.md (85%) create mode 100644 CONTRIBUTING.md delete mode 100644 CONTRIBUTING.rst create mode 100644 README.md delete mode 100644 README.rst diff --git a/.github/workflows/ci.yml b/.github/workflows/lint.yml similarity index 96% rename from .github/workflows/ci.yml rename to .github/workflows/lint.yml index 44615ef..275313a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/lint.yml @@ -1,4 +1,4 @@ -name: CI +name: Lint on: push: branches: diff --git a/AUTHORS.rst b/AUTHORS.md similarity index 85% rename from AUTHORS.rst rename to AUTHORS.md index 6cc5393..df7f28c 100644 --- a/AUTHORS.rst +++ b/AUTHORS.md @@ -1,14 +1,8 @@ -Main authors (commit rights to the main repository) -=================================================== +# Current Maintainer(s) -* Chris Glass -* Diederik van der Boor -* Charlie Denton -* Jerome Leclanche +* Brian Kohan - -Contributors -============= +## Contributors * Abel Daniel * Adam Chainz @@ -70,8 +64,10 @@ Contributors * Vail Gold - -Former authors / maintainers -============================ +## Former authors / maintainers * Bert Constantin 2009/2010 (Original author, disappeared from the internet :( ) +* Chris Glass +* Diederik van der Boor +* Charlie Denton +* Jerome Leclanche diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b1eae2b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,51 @@ +# Contributing + +[![Jazzband](https://jazzband.co/static/img/badge.svg)](https://jazzband.co/) + +This is a [Jazzband](https://jazzband.co) project. By contributing you agree to abide by the [Contributor Code of Conduct](https://jazzband.co/about/conduct) and follow the [guidelines](https://jazzband.co/about/guidelines). + +Contributions are encouraged! Please use the issue page to submit feature requests or bug reports. Issues with attached PRs will be given priority and have a much higher likelihood of acceptance. + +We are actively seeking additional maintainers. If you're interested, [contact me](https://github.com/bckohan). + +## Installation + +### Install Just + +We provide a platform independent justfile with recipes for all the development tasks. You should [install just](https://just.systems/man/en/installation.html) if it is not on your system already. + +`[django-polymorphic](https://pypi.python.org/pypi/django-polymorphic)` uses [uv](https://docs.astral.sh/uv) for environment, package, and dependency management. ``just setup`` will install the necessary build tooling if you do not already have it: + +```shell +just setup +``` + +## Documentation + +TODO + +## Static Analysis + +TODO + +## Running Tests + +TODO + +## Versioning + +[django-polymorphic](https://pypi.python.org/pypi/django-polymorphic) strictly adheres to [semantic versioning](https://semver.org). + +## Issuing Releases + +The release workflow is triggered by tag creation. You must have [git tag signing enabled](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). Our justfile has a release shortcut: + +```bash +just release x.x.x +``` + +## Just Recipes + +```bash + +``` diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index fc3af32..0000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. image:: https://jazzband.co/static/img/jazzband.svg - :target: https://jazzband.co/ - :alt: Jazzband - -This is a `Jazzband `_ project. By contributing you agree to abide by the `Contributor Code of Conduct `_ and follow the `guidelines `_. diff --git a/README.md b/README.md new file mode 100644 index 0000000..f803e8e --- /dev/null +++ b/README.md @@ -0,0 +1,82 @@ +# django-polymorphic + +[![License: BSD](https://img.shields.io/badge/License-BSD-blue.svg)](https://opensource.org/license/bsd-3-clause) +[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) +[![PyPI version](https://badge.fury.io/py/django-polymorphic.svg)](https://pypi.python.org/pypi/django-polymorphic/) +[![PyPI pyversions](https://img.shields.io/pypi/pyversions/django-polymorphic.svg)](https://pypi.python.org/pypi/django-polymorphic/) +[![PyPI djversions](https://img.shields.io/pypi/djversions/django-polymorphic.svg)](https://pypi.org/project/django-polymorphic/) +[![PyPI status](https://img.shields.io/pypi/status/django-polymorphic.svg)](https://pypi.python.org/pypi/django-polymorphic) +[![Documentation Status](https://readthedocs.org/projects/django-polymorphic/badge/?version=latest)](http://django-polymorphic.readthedocs.io/?badge=latest/) +[![Code Cov](https://img.shields.io/codecov/c/github/jazzband/django-polymorphic/master.svg)](https://codecov.io/github/jazzband/django-polymorphic?branch=master) +[![Test Status](https://github.com/jazzband/django-polymorphic/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/jazzband/django-polymorphic/actions/workflows/test.yml?query=branch:main) +[![Lint Status](https://github.com/jazzband/django-polymorphic/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/jazzband/django-polymorphic/actions/workflows/lint.yml?query=branch:main) +[![Published on Django Packages](https://img.shields.io/badge/Published%20on-Django%20Packages-0c3c26)](https://djangopackages.org/packages/p/django-polymorphic/) +[![Jazzband](https://jazzband.co/static/img/badge.svg)](https://jazzband.co/) + +## Polymorphic Models for Django + +[django-polymorphic](https://pypi.python.org/pypi/django-polymorphic) simplifies using inherited models in [Django](https://djangoproject.com) projects. When a query is made at the base model, the inherited model classes are returned. + +When we store models that inherit from a ``Project`` model... + +```python + + >>> Project.objects.create(topic="Department Party") + >>> ArtProject.objects.create(topic="Painting with Tim", artist="T. Turner") + >>> ResearchProject.objects.create(topic="Swallow Aerodynamics", supervisor="Dr. Winter") +``` + +...and want to retrieve all our projects, the subclassed models are returned! + +```python + + >>> Project.objects.all() + [ , + , + ] +``` + +Using vanilla Django, we get the base class objects, which is rarely what we wanted: + +```python + + >>> Project.objects.all() + [ , + , + ] +``` + +This also works when the polymorphic model is accessed via +ForeignKeys, ManyToManyFields or OneToOneFields. + +### Features + +* Full admin integration. +* ORM integration: + + * support for ForeignKey, ManyToManyField, OneToOneField descriptors. + * Filtering/ordering of inherited models (``ArtProject___artist``). + * Filtering model types: ``instance_of(...)`` and ``not_instance_of(...)`` + * Combining querysets of different models (``qs3 = qs1 | qs2``) + * Support for custom user-defined managers. +* Uses the minimum amount of queries needed to fetch the inherited models. +* Disabling polymorphic behavior when needed. + + +**Note:** While [django-polymorphic](https://pypi.python.org/pypi/django-polymorphic) makes subclassed models easy to use in Django, we still encourage to use them with caution. Each subclassed model will require Django to perform an ``INNER JOIN`` to fetch the model fields from the database. While taking this in mind, there are valid reasons for using subclassed models. That's what this library is designed for! + +The current release of [django-polymorphic](https://pypi.python.org/pypi/django-polymorphic) supports Django 2.2 - 5.2 on Python 3.9+. + +For more information, see the [documentation at Read the Docs](https://django-polymorphic.readthedocs.io). + +### Installation + +Install using ``pip``\ ... + +```bash + $ pip install django-polymorphic +``` + +## License + +[django-polymorphic](https://pypi.python.org/pypi/django-polymorphic) uses the same license as Django (BSD-like). diff --git a/README.rst b/README.rst deleted file mode 100644 index a6ac4bc..0000000 --- a/README.rst +++ /dev/null @@ -1,99 +0,0 @@ -.. list-table:: - :header-rows: 0 - :widths: auto - - * - .. image:: https://github.com/jazzband/django-polymorphic/actions/workflows/test.yml/badge.svg - :target: https://github.com/jazzband/django-polymorphic/actions/workflows/test.yml - - .. image:: https://img.shields.io/pypi/v/django-polymorphic.svg - :target: https://pypi.python.org/pypi/django-polymorphic/ - - .. image:: https://img.shields.io/codecov/c/github/jazzband/django-polymorphic/master.svg - :target: https://codecov.io/github/jazzband/django-polymorphic?branch=master - - .. image:: https://readthedocs.org/projects/django-polymorphic/badge/?version=stable - :target: https://django-polymorphic.readthedocs.io/en/stable/ - - .. image:: https://jazzband.co/static/img/badge.svg - :target: https://jazzband.co/ - :alt: Jazzband - - - -Polymorphic Models for Django -============================= - -Django-polymorphic simplifies using inherited models in Django projects. -When a query is made at the base model, the inherited model classes are returned. - -When we store models that inherit from a ``Project`` model... - -.. code-block:: python - - >>> Project.objects.create(topic="Department Party") - >>> ArtProject.objects.create(topic="Painting with Tim", artist="T. Turner") - >>> ResearchProject.objects.create(topic="Swallow Aerodynamics", supervisor="Dr. Winter") - -...and want to retrieve all our projects, the subclassed models are returned! - -.. code-block:: python - - >>> Project.objects.all() - [ , - , - ] - -Using vanilla Django, we get the base class objects, which is rarely what we wanted: - -.. code-block:: python - - >>> Project.objects.all() - [ , - , - ] - -This also works when the polymorphic model is accessed via -ForeignKeys, ManyToManyFields or OneToOneFields. - -Features --------- - -* Full admin integration. -* ORM integration: - - * support for ForeignKey, ManyToManyField, OneToOneField descriptors. - * Filtering/ordering of inherited models (``ArtProject___artist``). - * Filtering model types: ``instance_of(...)`` and ``not_instance_of(...)`` - * Combining querysets of different models (``qs3 = qs1 | qs2``) - * Support for custom user-defined managers. -* Uses the minimum amount of queries needed to fetch the inherited models. -* Disabling polymorphic behavior when needed. - - -**Note:** While *django-polymorphic* makes subclassed models easy to use in Django, -we still encourage to use them with caution. Each subclassed model will require -Django to perform an ``INNER JOIN`` to fetch the model fields from the database. -While taking this in mind, there are valid reasons for using subclassed models. -That's what this library is designed for! - -The current release of *django-polymorphic* supports Django 2.2 - 4.0 on Python 3.6+. - -For more information, see the `documentation at Read the Docs `_. - -Installation ------------- - -Install using ``pip``\ ... - -.. code:: bash - - $ pip install django-polymorphic - - -At the moment we have an unoffical version (4.0.0a). While we wait to gain access to pip. If you want to use the latest version (which works for Django >4.0.0). You can install it using - -.. code:: bash - - pip install git+https://github.com/jazzband/django-polymorphic.git@v4.0.0a#egg=django-polymorphic - - -License -======= - -Django-polymorphic uses the same license as Django (BSD-like). diff --git a/pyproject.toml b/pyproject.toml index 37f0ed6..dea1b73 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" name = "django-polymorphic" dynamic = ["version"] description = "Seamless polymorphic inheritance for Django models." -readme = "README.rst" +readme = "README.md" license = "BSD-3-Clause" license-files = [ "LICENSE" ] requires-python = ">=3.9,<4.0" @@ -62,7 +62,7 @@ dependencies = [ "Repository" = "https://github.com/jazzband/django-polymorphic" "Issues" = "https://github.com/jazzband/django-polymorphic/issues" "Changelog" = "https://django-polymorphic.readthedocs.io/en/stable/changelog.html" -"Code_of_Conduct" = "https://github.com/django-commons/membership/blob/main/CODE_OF_CONDUCT.md" +"Code_of_Conduct" = "https://jazzband.co/about/conduct" [tool.uv] package = true