feat(ci): add GitHub Actions workflows for CI, production, and test PyPI publishing with uv integration and update .gitignore and docs for development environment

Author: imakecodes

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - uses: astral-sh/setup-uv@v5
+      - name: Sync dependencies
+        run: uv sync --locked
+      - name: Run tests
+        run: uv run pytest
+      - name: Run lint
+        run: uv run ruff check .

.github/workflows/production.yml

@@ -7,20 +7,17 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
-    - uses: actions/checkout@v1
-    - name: Set up Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools wheel twine
-    - name: Build and publish
-      env:
-        TWINE_USERNAME: __token__
-        TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
-      run: |
-        python setup.py sdist bdist_wheel
-        twine upload dist/*
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - uses: astral-sh/setup-uv@v5
+      - name: Build package
+        run: uv build
+      - name: Publish package
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish --trusted-publishing never

.github/workflows/publish-to-test-pypi.yml

@@ -6,21 +6,17 @@ on: push
 jobs:
   release:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
-    - uses: actions/checkout@v1
-    - name: Set up Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools wheel twine
-    - name: Build and publish
-      env:
-        TWINE_USERNAME: __token__
-        TWINE_PASSWORD: ${{ secrets.PYPI_TEST_TOKEN }}
-        TWINE_REPOSITORY_URL: https://test.pypi.org/legacy/
-      run: |
-        python setup.py sdist bdist_wheel
-        twine upload dist/*
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - uses: astral-sh/setup-uv@v5
+      - name: Build package
+        run: uv build
+      - name: Publish package
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TEST_TOKEN }}
+        run: uv publish --publish-url https://test.pypi.org/legacy/ --check-url https://test.pypi.org/simple/ --trusted-publishing never

.gitignore

@@ -104,6 +104,7 @@ celerybeat.pid
 # Environments
 .env
 .venv
+.uv-cache/
 env/
 venv/
 ENV/

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing
+
+## Prerequisites
+
+- `uv` installed locally
+- Python `3.13` available, as declared in `.python-version`
+
+## Bootstrap
+
+```bash
+uv sync --locked
+```
+
+If your environment cannot write to the default uv cache location, prefix the commands with `UV_CACHE_DIR=.uv-cache`.
+
+If you change dependencies in `pyproject.toml`, regenerate the lockfile with:
+
+```bash
+uv lock
+uv sync
+```
+
+## Daily commands
+
+Run the unit tests:
+
+```bash
+uv run pytest
+```
+
+Run lint checks:
+
+```bash
+uv run ruff check .
+```
+
+Build the package:
+
+```bash
+uv build
+```
+
+## Project layout
+
+- `django_dbml/management/commands/dbml.py`: command that inspects Django model metadata and renders DBML
+- `django_dbml/utils.py`: helper utilities used by the generator
+- `tests/testapp/`: isolated Django app used to exercise the extension
+- `tests/test_command.py`: command-level tests
+- `tests/test_utils.py`: unit tests for helper behavior
+
+## Release flow
+
+The repository publishes from GitHub Actions using `uv build` and `uv publish`. Before releasing, run:
+
+```bash
+uv run pytest
+uv run ruff check .
+uv build
+```
+
+The detailed development guide lives in `docs/development.md`.

README.md

@@ -2,32 +2,46 @@
 
 This app can generate a DBML output for all installed models.
 
-## How to install and use?
+## Installation
 
-#### 1. Install the django-dbml package
-
-```
+```bash
 pip install django-dbml
 ```
 
-#### 2. Put django_dbml on your django settings
+## Usage
+
+Add `django_dbml` to `INSTALLED_APPS`:
 
 ```python
-'...',
-'django_dbml',
-'...',
+INSTALLED_APPS = [
+    # ...
+    "django_dbml",
+]
 ```
 
-#### 3. Run the command to generate a DBML schema based on your Django models
+Generate DBML from all installed models:
 
 ```bash
-$ python manage.py dbml
+python manage.py dbml
 ```
 
-To generate DBML for a subset of your models, specify one or more Django app 
-names or models by app_label or app_label.ModelName. Related tables will still 
+To generate DBML for a subset of your models, specify one or more Django app
+names or models by `app_label` or `app_label.ModelName`. Related tables will still
 be included in the DBML.
 
+## Development
+
+This repository is now managed with `uv`.
+
+```bash
+uv sync --locked
+uv run pytest
+uv run ruff check .
+uv build
+```
+
+Development instructions live in [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/development.md](docs/development.md).
+
 # Thanks
 
 The initial code was based on https://github.com/hamedsj/DbmlForDjango project

django_dbml/management/commands/dbml.py

@@ -99,7 +99,7 @@ def get_app_tables(self, app_labels) -> list:
 
         # if no apps are specified, process all models
         if not app_labels:
-            return apps.get_models()
+            return list(apps.get_models())
 
         # get specific models when app or app.model is specified
         app_tables = []
@@ -114,13 +114,45 @@ def get_app_tables(self, app_labels) -> list:
             except LookupError as e:
                 raise CommandError(str(e))  # noqa: B904
 
-            app_config = apps.get_app_config(app_label)
             if model_label:
                 app_tables.append(app_config.get_model(model_label))
             else:
                 app_tables.extend(app_config.get_models())
 
-        return app_tables
+        return self.include_related_models(app_tables)
+
+    def include_related_models(self, models_to_process: list[type[Model]]) -> list[type[Model]]:
+        """Expand a selected set of models to include their forward-related models."""
+
+        ignore_types = (models.fields.reverse_related.ManyToOneRel, models.fields.reverse_related.ManyToManyRel)
+        collected_models: list[type[Model]] = []
+        pending_models = list(models_to_process)
+        seen_models: set[type[Model]] = set()
+
+        while pending_models:
+            model = pending_models.pop(0)
+            if model in seen_models:
+                continue
+
+            seen_models.add(model)
+            collected_models.append(model)
+
+            for field in model._meta.get_fields():
+                if isinstance(field, ignore_types):
+                    continue
+
+                if isinstance(field, (models.fields.related.ForeignKey, models.fields.related.OneToOneField)):
+                    pending_models.append(field.related_model)
+                    continue
+
+                if isinstance(field, models.fields.related.ManyToManyField):
+                    pending_models.append(field.related_model)
+
+                    through_model = field.remote_field.through
+                    if through_model is not None and not through_model._meta.auto_created:
+                        pending_models.append(through_model)
+
+        return collected_models
 
     def get_tl_module_name(self, model: Model) -> str:
         """Get top level module of model."""
@@ -173,8 +205,8 @@ def choices_to_markdown_table(self, choices: list) -> str:
 
     def handle(self, *app_labels, **kwargs):  # noqa: D102, PLR0912, PLR0914, PLR0915
         self.options = kwargs
-        project_name = self.options["add_project_name"]
-        project_notes = self.options["add_project_notes"]
+        project_name = self.options["add_project_name"] or "Django DBML"
+        project_notes = self.options["add_project_notes"] or "Generated from Django models."
 
         ignore_types = (models.fields.reverse_related.ManyToOneRel, models.fields.reverse_related.ManyToManyRel)
 
@@ -392,7 +424,7 @@ def handle(self, *app_labels, **kwargs):  # noqa: D102, PLR0912, PLR0914, PLR091
             if app_table.__doc__:
                 tables[table_name]["note"] += f"\n{app_table.__doc__}"
 
-            if app_table._meta.db_table_comment:
+            if getattr(app_table._meta, "db_table_comment", ""):
                 comment = app_table._meta.db_table_comment.replace('"', '\"')
                 tables[table_name]["note"] += f'\n\n*DB comment: {comment}*'
 
@@ -495,4 +527,4 @@ def handle(self, *app_labels, **kwargs):  # noqa: D102, PLR0912, PLR0914, PLR091
                 f.write(output_string)
             logger.info('Generated dbml file to %s', output_file)
         else:
-            print(output_string)  # noqa: T201
+            self.stdout.write(output_string, ending="")

django_dbml/tests.py

@@ -0,0 +1,67 @@
+# Development Guide
+
+## What this extension does
+
+`django-dbml` is a Django app that converts the metadata exposed by Django models into DBML. The main entrypoint is the `dbml` management command.
+
+## How the generator is organized
+
+`django_dbml/management/commands/dbml.py` is responsible for:
+
+1. Selecting which models should be part of the schema.
+2. Expanding the selection to include forward-related models.
+3. Mapping Django field classes to DBML field types.
+4. Rendering tables, enums, indexes, notes, and references.
+
+`django_dbml/utils.py` contains the field-name normalization helper used during type mapping.
+
+## Local development workflow
+
+Install dependencies:
+
+```bash
+uv sync --locked
+```
+
+Run the full test suite:
+
+```bash
+uv run pytest
+```
+
+Run linting:
+
+```bash
+uv run ruff check .
+```
+
+Build artifacts locally:
+
+```bash
+uv build
+```
+
+If `uv` cannot write to the default cache directory in your environment, use:
+
+```bash
+UV_CACHE_DIR=.uv-cache uv sync --locked
+UV_CACHE_DIR=.uv-cache uv run pytest
+```
+
+If you update dependencies, refresh the lockfile before syncing again:
+
+```bash
+uv lock
+uv sync
+```
+
+## How to extend the command safely
+
+When adding support for a new Django field or DBML feature:
+
+1. Update the rendering logic in `django_dbml/management/commands/dbml.py`.
+2. Add or adjust models inside `tests/testapp/models.py` to cover the new metadata shape.
+3. Add assertions in `tests/test_command.py` for the rendered DBML.
+4. If the change is isolated to a helper, add a focused unit test in `tests/test_utils.py`.
+
+Prefer command-level tests for behavior that depends on Django model metadata, because the package's value is in the final DBML output rather than in isolated internal methods.