drivendataorg · jayqi · Mar 30, 2024 · Feb 24, 2024 · Feb 26, 2024 · Feb 26, 2024
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -32,7 +32,8 @@ jobs:
  PACKAGE_VERSION=$(.nox/dev/bin/python -c "import erdantic; print(erdantic.__version__)")
  echo "Package version: [$PACKAGE_VERSION]"
  [ ${{ github.event.release.tag_name }} == "v$PACKAGE_VERSION" ] || { exit 1; }
- echo "::set-output name=major_minor_version::v${PACKAGE_VERSION%.*}"
+ echo "full_version=v$PACKAGE_VERSION" >> $GITHUB_ENV
+ echo "major_minor_version=v${PACKAGE_VERSION%.*}" >> $GITHUB_ENV
 
  - name: Build package
  run: |
@@ -57,7 +58,19 @@ jobs:
  password: ${{ secrets.PYPI_PROD_PASSWORD }}
  skip_existing: false
 
- - name: Stage docs on gh-pages
+ - name: Stage docs on gh-pages (release candidate)
+ if: contains(steps.version.outputs.full_version, 'rc')
+ working-directory: docs
+ run: |
+ git fetch origin gh-pages --depth=1
+ git config user.name github-actions[bot]
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+ mike deploy --push \
+ ${{ steps.version.outputs.major_minor_version }}rc \
+ --title="${{ steps.version.outputs.major_minor_version }}rc"
+
+ - name: Stage docs on gh-pages (stable)
+ if: ! contains(steps.version.outputs.full_version, 'rc')
  working-directory: docs
  run: |
  git fetch origin gh-pages --depth=1

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -30,7 +30,7 @@ jobs:
  - name: Lint
  run: |
  nox -s lint --verbose
- 
+
  - name: Typecheck
  run: |
  nox -s typecheck --verbose
@@ -41,7 +41,7 @@ jobs:
  runs-on: ${{ matrix.os }}
  strategy:
  matrix:
- os: [ubuntu-latest, macos-latest, windows-latest]
+ os: [ubuntu-latest, macos-latest]
  python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
  steps:
@@ -62,6 +62,14 @@ jobs:
  run: |
  nox -s tests-${{ matrix.python-version }} --verbose
 
+ - name: Upload test outputs
+ uses: actions/upload-artifact@v4
+ if: success() || failure()
+ with:
+ name: test-outputs-${{ matrix.os }}-python-${{ matrix.python-version }}
+ path: tests/_outputs
+
+
  - name: Upload coverage to codecov
  uses: codecov/codecov-action@v3
  with:
@@ -88,11 +96,16 @@ jobs:
  pipx install nox
  pipx install uv
 
- - name: Build distribution and test installation
- shell: bash
+ - name: Build distribution
  run: |
  nox -s build
+
+ - name: Test wheel with extras matrix
+ run: |
  nox -s test_wheel --verbose
+
+ - name: Test sdist
+ run: |
  nox -s test_sdist --verbose
 
  docs:

diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,12 @@
 .vscode
-docs/docs/index.md
-docs/docs/changelog.md
-docs/docs/cli.md
-docs/docs/examples/diagram.png
+
+docs/docs/examples/
+docs/notebooks/diagram.png
+docs/notebooks/diagram.svg
 docs/site
 
+tests/_outputs
+
 ### Python
 
 # Byte-compiled / optimized / DLL files

diff --git a/HISTORY.md b/HISTORY.md
@@ -1,10 +1,52 @@
 # erdantic Changelog
 
-## v0.8.0 (Unreleased)
+## v1.0.0rc1 Release Candidate (2024-03-30)
 
-- Removed support for Python 3.7. ([PR #102](https://github.com/drivendataorg/erdantic/pull/102))
-- Changed rendering of type names to use the [typenames](https://github.com/jayqi/typenames) library. This should generally produce with same rendered outputs, with the following exception:
+_This is a pre-release version for v1.0.0._
+
+> [!IMPORTANT]
+> This release features significant changes to erdantic, primarily to the backend process of analyzing models and representing data. If you have been primarily using the CLI or the convenience functions `create`, `draw`, and `to_dot`, then your code may continue to work without any changes. If you are doing something more advanced, you may need to update your code.
+
+### CLI changes
+
+- Deprecated `--termini` option. Use the new `--terminal-model` option instead. The shorthand option `-t` remains the same. The `--termini` option still works but will emit a deprecation warning.
+
+### Convenience function changes
+
+- Deprecated `termini` argument for `create`, `draw`, and `to_dot` functions. Use the new `terminal_models` argument instead. The `termini` argument still works but will emit a deprecation warning.
+- Added `graph_attr`, `node_attr`, and `edge_attr` arguments to the `draw` and `to_dot` functions that allow you to override attributes on the generated pygraphviz object for the diagram.
+
+### Visual changes
+
+A few changes have been made to the visual content of rendered diagrams.
+
+- Changed the extraction of type names to use the [typenames](https://github.com/jayqi/typenames) library. This should generally produce identical rendered outputs as before, with the following exception:
  - Removed the special case behavior for rendering enum classes. Enums now just show the class name without inheritance information.
+- Changed collection fields (e.g., `List[TargetModel]`) to display as a "many" relationship (crow) instead of a "zero-or-many" relationship (odot + crow), treating the modality of the field as unspecified. A field will only be displayed as "zero-or-many" (odot + crow) if it is explicitly optional, like `Optional[List[TargetModel]]`.
+- Fixed incorrect representation of manyness for type annotations where the outermost annotation wasn't a collection type. ([Issue #105](https://github.com/drivendataorg/erdantic/issues/105))
+
+### Support for attrs
+
+- Added support for [attrs](https://www.attrs.org/en/stable/index.html) classes, i.e., classes decorated by `attrs.define`. The source code for attrs support can be found in the new module `erdantic.plugins.attrs`.
+- Added new example module `erdantic.examples.attrs`.
+
+### Backend changes
+
+Significant changes have been made to the library backend to more strongly separate the model analysis process, the extracted data, and the diagram rendering process. We believe this more structured design facilitates customizing diagrams and simplifies the implementation for each data modeling framework. Please see the new documentation pages ["Customizing diagrams"](http://erdantic.drivendata.org/stable/customizing/) and ["Extending or modifying erdantic"](http://erdantic.drivendata.org/stable/extending/) for details on the new design.
+
+A summary of some key changes is below:
+
+- Removed the adapter base classes `Model` and `Field` and the conrete adapters `DataClassModel`, `DataClassField`, `PydanticModel`, and `PydanticField`.
+ - Added new Pydantic models `ModelInfo` and `FieldInfo` to replace the adapter system. These new models hold static data that have been extracted from models that erdantic analyzed.
+- Removed the adapter system and associated objects such as `model_adapter_registry` and `register_model_adapter`.
+ - Added new plugin system to replace the adapter system as the way that modeling frameworks are supported. Plugins must implement two functions—a predicate function and a field extractor function—and be registered using `register_plugin`. All objects related to plugins can be found in the new `erdantic.plugins` module and its submodules.
+- Renamed `erdantic.typing` module to `erdantic.typing_utils`.
+
+### Other
+
+- Added [PEP 561 `py.typed` marker file](https://peps.python.org/pep-0561/#packaging-type-information) to indicate that the package supports type checking.
+- Added IPython special method for pretty-print string representations of `EntityRelationshipDiagram` instances.
+- Removed support for Python 3.7. ([PR #102](https://github.com/drivendataorg/erdantic/pull/102))
 
 ## v0.7.0 (2024-02-11)
 

diff --git a/README.md b/README.md
@@ -7,15 +7,19 @@
 [![tests](https://github.com/drivendataorg/erdantic/workflows/tests/badge.svg?branch=main)](https://github.com/drivendataorg/erdantic/actions?query=workflow%3Atests+branch%3Amain)
 [![codecov](https://codecov.io/gh/drivendataorg/erdantic/branch/main/graph/badge.svg)](https://codecov.io/gh/drivendataorg/erdantic)
 
+> [!NOTE]
+> erdantic v1.0 is coming soon and involves big backend changes. See the [changelog](./HISTORY.md) for more information.
+
 **erdantic** is a simple tool for drawing [entity relationship diagrams (ERDs)](https://en.wikipedia.org/wiki/Data_modeling#Entity%E2%80%93relationship_diagrams) for Python data model classes. Diagrams are rendered using the venerable [Graphviz](https://graphviz.org/) library. Supported data modeling frameworks are:
 
 - [Pydantic V2](https://docs.pydantic.dev/latest/)
 - [Pydantic V1 legacy](https://docs.pydantic.dev/latest/migration/#continue-using-pydantic-v1-features)
+- [attrs](https://www.attrs.org/en/stable/)
 - [dataclasses](https://docs.python.org/3/library/dataclasses.html) from the Python standard library
 
-Features include a convenient CLI, automatic native rendering in Jupyter notebooks, and easy extensibility to other data modeling frameworks. Docstrings are even accessible as tooltips for SVG outputs. Great for adding a simple and clean data model reference to your documentation.
+You can use erdantic either as a convenient CLI or as a Python library. Great for adding a simple and clean data model reference to your documentation.
 
-<object type="image/svg+xml" data="https://raw.githubusercontent.com/drivendataorg/erdantic/main/docs/docs/examples/pydantic.svg" width="100%" typemustmatch><img alt="Example diagram created by erdantic" src="https://raw.githubusercontent.com/drivendataorg/erdantic/main/docs/docs/examples/pydantic.svg"></object>
+<object type="image/svg+xml" data="./docs/docs/assets/example_diagram.svg" width="100%" typemustmatch><img alt="Example diagram created by erdantic" src="./docs/docs/assets/example_diagram.svg"></object>
 
 ## Installation
 
@@ -39,15 +43,17 @@ You can get the development version from GitHub with:
 pip install git+https://github.com/drivendataorg/erdantic.git#egg=erdantic
 ```
 
-## Quick Usage
+## Quick usage
+
+First, make sure that the data model classes that you want to include in your diagram are importable. This means the code with your models should either be available on your [`sys.path`](https://docs.python.org/3/library/sys_path_init.html) or installed into the same virtual environment as erdantic.
 
-The fastest way to produce a diagram like the above example is to use the erdantic CLI. Simply specify the full dotted path to your data model class and an output path. The rendered format is interpreted from the filename extension.
+The fastest way to produce a diagram like the above example is to use the erdantic CLI. Simply specify the full dotted import path to your model and an output file path. The rendered format is interpreted from the filename extension.
 
 ```bash
 erdantic erdantic.examples.pydantic.Party -o diagram.png
 ```
 
-You can also import the erdantic Python library and use its functions.
+You can also import the erdantic Python library. This lets you inspect the diagram data and potentially modify it. You will have greater ability to customize the diagram in Python.
 
 ```python
 import erdantic as erd
@@ -58,8 +64,11 @@ erd.draw(Party, out="diagram.png")
 
 # Or create a diagram object that you can inspect and do stuff with
 diagram = erd.create(Party)
-diagram.models
-#> [PydanticModel(Adventurer), PydanticModel(Party), PydanticModel(Quest), PydanticModel(QuestGiver)]
+list(diagram.models.keys())
+#> [ 'erdantic.examples.pydantic.Adventurer',
+#> 'erdantic.examples.pydantic.Party',
+#> 'erdantic.examples.pydantic.Quest',
+#> 'erdantic.examples.pydantic.QuestGiver']
 diagram.draw("diagram.png")
 ```
 

diff --git a/docs/docs/api-reference/base.md b/docs/docs/api-reference/base.md
diff --git a/docs/docs/api-reference/convenience.md b/docs/docs/api-reference/convenience.md
@@ -0,0 +1,3 @@
+# erdantic.convenience
+
+::: erdantic.convenience
diff --git a/docs/docs/api-reference/core.md b/docs/docs/api-reference/core.md
@@ -0,0 +1,3 @@
+# erdantic.core
+
+::: erdantic.core
diff --git a/docs/docs/api-reference/dataclasses.md b/docs/docs/api-reference/dataclasses.md
diff --git a/docs/docs/api-reference/erd.md b/docs/docs/api-reference/erd.md
diff --git a/docs/docs/api-reference/examples/attrs.md b/docs/docs/api-reference/examples/attrs.md
@@ -0,0 +1,3 @@
+# erdantic.examples.attrs
+
+::: erdantic.examples.attrs
diff --git a/...ocs/api-reference/examples.dataclasses.md → ...ocs/api-reference/examples/dataclasses.md b/...ocs/api-reference/examples.dataclasses.md → ...ocs/api-reference/examples/dataclasses.md
diff --git a/docs/docs/api-reference/examples.pydantic.md → docs/docs/api-reference/examples/pydantic.md b/docs/docs/api-reference/examples.pydantic.md → docs/docs/api-reference/examples/pydantic.md
diff --git a/docs/docs/api-reference/examples/pydantic_v1.md b/docs/docs/api-reference/examples/pydantic_v1.md
@@ -0,0 +1,7 @@
+# erdantic.examples.pydantic
+
+::: erdantic.examples.pydantic
+ selection:
+ filters:
+ - "!^_"
+ - "!^Config$"
diff --git a/docs/docs/api-reference/plugins/attrs.md b/docs/docs/api-reference/plugins/attrs.md
@@ -0,0 +1,3 @@
+# erdantic.plugins.attrs
+
+::: erdantic.plugins.attrs
diff --git a/docs/docs/api-reference/plugins/dataclasses.md b/docs/docs/api-reference/plugins/dataclasses.md
@@ -0,0 +1,3 @@
+# erdantic.plugins.dataclasses
+
+::: erdantic.plugins.dataclasses
diff --git a/docs/docs/api-reference/plugins/index.md b/docs/docs/api-reference/plugins/index.md
@@ -0,0 +1,3 @@
+# erdantic.plugins
+
+::: erdantic.plugins
diff --git a/docs/docs/api-reference/plugins/pydantic.md b/docs/docs/api-reference/plugins/pydantic.md
@@ -0,0 +1,3 @@
+# erdantic.plugins.pydantic
+
+::: erdantic.plugins.pydantic
diff --git a/docs/docs/api-reference/pydantic.md b/docs/docs/api-reference/pydantic.md
diff --git a/docs/docs/api-reference/typing_utils.md b/docs/docs/api-reference/typing_utils.md
@@ -0,0 +1,3 @@
+# erdantic.typing_utils
+
+::: erdantic.typing_utils
diff --git a/docs/docs/assets/edge-many-unspecified.png b/docs/docs/assets/edge-many-unspecified.png
diff --git a/docs/docs/assets/edge-many-zero.png b/docs/docs/assets/edge-many-zero.png
diff --git a/docs/docs/assets/edge-one-one.png b/docs/docs/assets/edge-one-one.png
diff --git a/docs/docs/assets/edge-one-zero.png b/docs/docs/assets/edge-one-zero.png
diff --git a/docs/docs/assets/erdantic_diagram.png b/docs/docs/assets/erdantic_diagram.png