From 6e01468c130ba02d2ac716c1576bfe0fb0376809 Mon Sep 17 00:00:00 2001 From: Christodoulos Tsoulloftas Date: Sat, 30 Mar 2024 11:44:00 +0200 Subject: [PATCH] docs: Cleanup a few issues --- .pre-commit-config.yaml | 9 +- README.md | 11 +- docs/codegen/architecture.md | 6 +- docs/codegen/config.md | 2 +- docs/codegen/intro.md | 6 +- docs/models/fields.md | 2 +- mkdocs.yml | 253 +++++++++--------- tests/integration/benchmarks/utils.py | 4 +- .../handlers/process_mixed_content_class.py | 2 +- .../handlers/rename_duplicate_classes.py | 2 - xsdata/codegen/mappers/dtd.py | 2 +- xsdata/codegen/utils.py | 2 +- xsdata/formats/dataclass/compat.py | 2 +- xsdata/formats/dataclass/filters.py | 2 +- 14 files changed, 155 insertions(+), 150 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0b00cb2cb..363399e6b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -7,6 +7,11 @@ repos: - id: trailing-whitespace - id: end-of-file-fixer - id: debug-statements + - repo: https://github.com/crate-ci/typos + rev: v1.19.0 + hooks: + - id: typos + exclude: ^tests/|.xsd$ - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.3.4 hooks: @@ -27,8 +32,10 @@ repos: - types-toposort args: [ "--check-untyped-defs", "--ignore-missing-imports" ] - repo: https://github.com/pre-commit/mirrors-prettier - rev: v3.1.0 + rev: v4.0.0-alpha.8 hooks: - id: prettier + additional_dependencies: + - prettier@3.2.5 types_or: [markdown] args: [--prose-wrap=always, --print-width=88] diff --git a/README.md b/README.md index a7bf6255f..b72ff46ff 100644 --- a/README.md +++ b/README.md @@ -37,14 +37,11 @@ $ xsdata tests/fixtures/primer/order.xsd --package tests.fixtures.primer ``` ```python ->>> # Parse XML ->>> from pathlib import Path >>> from tests.fixtures.primer import PurchaseOrder >>> from xsdata.formats.dataclass.parsers import XmlParser >>> ->>> xml_string = Path("tests/fixtures/primer/sample.xml").read_text() >>> parser = XmlParser() ->>> order = parser.from_string(xml_string, PurchaseOrder) +>>> order = parser.parse("tests/fixtures/primer/sample.xml", PurchaseOrder) >>> order.bill_to Usaddress(name='Robert Smith', street='8 Oak Avenue', city='Old Town', state='PA', zip=Decimal('95819'), country='US') ``` @@ -53,18 +50,22 @@ Check the [documentation](https://xsdata.readthedocs.io) for more ✨✨✨ ## Features -- Generate code from: +- Generate code from + - XML Schemas 1.0 & 1.1 - WSDL 1.1 definitions with SOAP 1.1 bindings - DTD external definitions - Directly from XML and JSON Documents - Extensive configuration to customize output - Pluggable code writer for custom output formats + - Default Output: + - Pure python dataclasses with metadata - Type hints with support for forward references and unions - Enumerations and inner classes - Support namespace qualified elements and attributes + - Data Binding: - XML and JSON parser, serializer - PyCode serializer diff --git a/docs/codegen/architecture.md b/docs/codegen/architecture.md index dfccb0996..d474ac1dc 100644 --- a/docs/codegen/architecture.md +++ b/docs/codegen/architecture.md @@ -20,9 +20,7 @@ if present. If the resource lacks an extension, the loader will attempt to locat specific syntax markings associated with the resource type. If a resource cannot be accessed, a warning is issued, and the program continues its -normal flow. - -In the case of circular imports, resources are loaded only once. +normal flow. In the case of circular imports, resources are loaded only once. ## Parse transfer objects @@ -72,7 +70,7 @@ graph LR ``` -- Remove duplicate overriden types: +- Remove duplicate overridden types: ```xml diff --git a/docs/codegen/config.md b/docs/codegen/config.md index cf0c43a75..1723d4329 100644 --- a/docs/codegen/config.md +++ b/docs/codegen/config.md @@ -112,7 +112,7 @@ The [dataclass][dataclasses.dataclass] parameters. A TypeError is raised if a field without a default value follows a field with a default value. This is true whether this occurs in a single class, or as a result of class inheritance. If this option is not enabled, the generator will mark all required fields without default values - as optional with. + as optional with default value `None`. ### Structure diff --git a/docs/codegen/intro.md b/docs/codegen/intro.md index cb36c1240..87d620b44 100644 --- a/docs/codegen/intro.md +++ b/docs/codegen/intro.md @@ -7,9 +7,9 @@ The code generator works with: - DTD external definitions - Directly from XML and JSON Documents -The resource [xsdata.codegen.transformer][xsdata.codegen.transformer] will detect and -switch parsers based on the resource extension otherwise it will do some heuristic -content searches. Before you start make sure the cli requirements are installed. +The [xsdata.codegen.transformer][xsdata.codegen.transformer] will detect and switch +parsers based on the resource extension otherwise it will do some heuristic content +searches. Before you start make sure the cli requirements are installed. ```console $ pip install xsdata[cli] diff --git a/docs/models/fields.md b/docs/models/fields.md index 952e3f614..3848b7616 100644 --- a/docs/models/fields.md +++ b/docs/models/fields.md @@ -256,7 +256,7 @@ Elements type represents repeatable choice elements. It's more commonly referred !!! Warning - A compound field can not contain ambigous types because it's impossible to infer the + A compound field can not contain ambiguous types because it's impossible to infer the element from the actual value. The xml contenxt will raise an error. The solution is to introduce intermediate diff --git a/mkdocs.yml b/mkdocs.yml index 6e82bf79e..ec877133e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,126 +1,127 @@ -site_name: "xsdata" -site_url: https://xsdata.readthedocs.io/ -site_description: >- - xsData is a complete data binding library for python allowing developers to - access and use XML and JSON documents as simple objects rather than using DOM. -repo_name: tefra/xsdata -repo_url: https://github.com/tefra/xsdata -edit_uri: edit/main/docs/ -exclude_docs: | - scripts/ - __pycache__/ - - -theme: - name: 'material' - custom_dir: docs/overrides - palette: - - media: "(prefers-color-scheme: light)" - scheme: default - primary: white - accent: deep purple - toggle: - icon: material/lightbulb-outline - name: "Switch to dark mode" - - media: "(prefers-color-scheme: dark)" - scheme: slate - primary: black - accent: deep purple - toggle: - icon: material/lightbulb - name: "Switch to light mode" - features: - - content.action.edit - - content.action.view - - content.code.annotate - - content.code.copy - - content.tooltips - - navigation.tabs - - navigation.footer - - navigation.top - - content.tabs.link - - search.suggest - logo: 'logo-small.svg' - favicon: 'favicon.png' - -watch: - - xsdata - -plugins: -- search -- minify: - minify_html: true -- markdown-exec -- gen-files: - scripts: - - docs/scripts/generate_api.py -- literate-nav: - nav_file: SUMMARY.md -- mkdocstrings: - handlers: - python: - load_external_modules: true - options: - members_order: source - show_source: true - show_root_heading: true - import: - - https://docs.python-requests.org/en/master/objects.inv - - https://docs.python.org/3/objects.inv - - https://lxml.de/apidoc/objects.inv - -markdown_extensions: - - admonition - - pymdownx.details - - pymdownx.snippets - - pymdownx.superfences: - custom_fences: - - name: "*" - class: "highlight" - format: !!python/name:pymdownx_superfence_filter_lines.do_format - validator: !!python/name:pymdownx_superfence_filter_lines.do_validate - - name: mermaid - class: mermaid - format: !!python/name:pymdownx.superfences.fence_code_format - - pymdownx.tabbed: - alternate_style: true - slugify: !!python/object/apply:pymdownx.slugs.slugify - kwds: - case: lower - -nav: -- Get Started: - - Welcome to xsdata: index.md - - Installation: installation.md - - Changelog: changelog.md - - Samples: samples.md - - PyPI: https://pypi.org/project/xsdata/ - - Conda: https://anaconda.org/conda-forge/xsdata -- Code Generator: - - Introduction: codegen/intro.md - - Configuration: codegen/config.md - - Docstring styles: codegen/docstrings.md - - DTD Modeling: codegen/dtd_modeling.md - - WSDL Modeling: codegen/wsdl_modeling.md - - Samples Modeling: codegen/samples_modeling.md - - Download Schemas: codegen/download_schemas.md - - Architecture: codegen/architecture.md -- Data Models: - - Classes: models/classes.md - - Fields: models/fields.md - - Types: models/types.md -- Data Binding: - - Basics: data_binding/basics.md - - XML Parsing: data_binding/xml_parsing.md - - XML Serializing: data_binding/xml_serializing.md - - JSON Parsing: data_binding/json_parsing.md - - JSON Serializing: data_binding/json_serializing.md - - Pycode Serializing: data_binding/pycode_serializing.md - - Tree Serializing: data_binding/tree_serializing.md - - Dict Decoding: data_binding/dict_decoding.md - - Dict Encoding: data_binding/dict_encoding.md -- FAQ: faq.md -- API: api/ -- Plugins: - - How-to: plugins/how_to.md - - List: plugins/list.md +site_name: "xsdata" +site_url: https://xsdata.readthedocs.io/ +site_description: >- + xsData is a complete data binding library for python allowing developers to + access and use XML and JSON documents as simple objects rather than using DOM. +repo_name: tefra/xsdata +repo_url: https://github.com/tefra/xsdata +edit_uri: edit/main/docs/ +exclude_docs: | + scripts/ + __pycache__/ + + +theme: + name: 'material' + custom_dir: docs/overrides + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: white + accent: deep purple + toggle: + icon: material/lightbulb-outline + name: "Switch to dark mode" + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: deep purple + toggle: + icon: material/lightbulb + name: "Switch to light mode" + features: + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.tabs + - navigation.footer + - navigation.top + - content.tabs.link + - search.suggest + logo: 'logo-small.svg' + favicon: 'favicon.png' + +watch: + - xsdata + +plugins: +- search +- minify: + minify_html: true +- markdown-exec +- gen-files: + scripts: + - docs/scripts/generate_api.py +- literate-nav: + nav_file: SUMMARY.md +- mkdocstrings: + handlers: + python: + load_external_modules: true + options: + members_order: source + show_source: true + show_root_heading: true + import: + - https://docs.python-requests.org/en/master/objects.inv + - https://docs.python.org/3/objects.inv + - https://lxml.de/apidoc/objects.inv + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.snippets: + dedent_subsections: true + - pymdownx.superfences: + custom_fences: + - name: "*" + class: "highlight" + format: !!python/name:pymdownx_superfence_filter_lines.do_format + validator: !!python/name:pymdownx_superfence_filter_lines.do_validate + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + slugify: !!python/object/apply:pymdownx.slugs.slugify + kwds: + case: lower + +nav: +- Get Started: + - Welcome to xsdata: index.md + - Installation: installation.md + - Changelog: changelog.md + - Samples: samples.md + - PyPI: https://pypi.org/project/xsdata/ + - Conda: https://anaconda.org/conda-forge/xsdata +- Code Generator: + - Introduction: codegen/intro.md + - Configuration: codegen/config.md + - Docstring styles: codegen/docstrings.md + - DTD Modeling: codegen/dtd_modeling.md + - WSDL Modeling: codegen/wsdl_modeling.md + - Samples Modeling: codegen/samples_modeling.md + - Download Schemas: codegen/download_schemas.md + - Architecture: codegen/architecture.md +- Data Models: + - Classes: models/classes.md + - Fields: models/fields.md + - Types: models/types.md +- Data Binding: + - Basics: data_binding/basics.md + - XML Parsing: data_binding/xml_parsing.md + - XML Serializing: data_binding/xml_serializing.md + - JSON Parsing: data_binding/json_parsing.md + - JSON Serializing: data_binding/json_serializing.md + - Pycode Serializing: data_binding/pycode_serializing.md + - Tree Serializing: data_binding/tree_serializing.md + - Dict Decoding: data_binding/dict_decoding.md + - Dict Encoding: data_binding/dict_encoding.md +- FAQ: faq.md +- API: api/ +- Plugins: + - How-to: plugins/how_to.md + - List: plugins/list.md diff --git a/tests/integration/benchmarks/utils.py b/tests/integration/benchmarks/utils.py index 5ce8c5518..7c3644040 100644 --- a/tests/integration/benchmarks/utils.py +++ b/tests/integration/benchmarks/utils.py @@ -17,8 +17,8 @@ def make_books(how_many: int): review=( "Lorem ipsum dolor sit amet, consectetur adipiscing elit. " "Integer at erat sagittis, accumsan mauris eu, egestas " - "quam. Nam tristique felis justo, vel iaculis ipsum cursus " - "at. Praesent varius enim ac nunc interdum placerat. " + "quam. Name tristique felis justo, vel iaculis ipsum cursus " + "at. Praesent various enim ac nunc interdum placerat. " "Integer porttitor, nibh at viverra vehicula, leo dui " "suscipit nisi, ornare laoreet eros neque nec mi. Proin." ), diff --git a/xsdata/codegen/handlers/process_mixed_content_class.py b/xsdata/codegen/handlers/process_mixed_content_class.py index b907364ce..784badc95 100644 --- a/xsdata/codegen/handlers/process_mixed_content_class.py +++ b/xsdata/codegen/handlers/process_mixed_content_class.py @@ -16,7 +16,7 @@ def process(self, target: Class): All other elements will be moved as the wildcard attr choices. Args: - target: Tha target class instance + target: The target class instance """ if not target.is_mixed: return diff --git a/xsdata/codegen/handlers/rename_duplicate_classes.py b/xsdata/codegen/handlers/rename_duplicate_classes.py index 844c94a7b..d026471e2 100644 --- a/xsdata/codegen/handlers/rename_duplicate_classes.py +++ b/xsdata/codegen/handlers/rename_duplicate_classes.py @@ -115,8 +115,6 @@ def add_numeric_suffix(self, target: Class): Args: target: The target class instance to rename - use_name: Whether simple or qualified names should be - used during renaming """ namespace, name = namespaces.split_qname(target.qname) new_qname = self.next_qname(namespace, name) diff --git a/xsdata/codegen/mappers/dtd.py b/xsdata/codegen/mappers/dtd.py index 4acc9f361..33644e0d0 100644 --- a/xsdata/codegen/mappers/dtd.py +++ b/xsdata/codegen/mappers/dtd.py @@ -35,7 +35,7 @@ def map(cls, dtd: Dtd) -> Iterator[Class]: @classmethod def build_class(cls, element: DtdElement, location: str) -> Class: - """Build a clas for the given element. + """Build a class for the given element. Args: element: The dtd element to be mapped diff --git a/xsdata/codegen/utils.py b/xsdata/codegen/utils.py index ae81f5116..5efedaedb 100644 --- a/xsdata/codegen/utils.py +++ b/xsdata/codegen/utils.py @@ -118,7 +118,7 @@ def copy_group_attributes(cls, source: Class, target: Class, attr: Attr): """Copy the attrs of the source class to the target class. The attr represents a reference to the source class which is - derived from xs:group or xs:attributeGroup and wil be removed. + derived from xs:group or xs:attributeGroup and will be removed. Args: source: The source class instance diff --git a/xsdata/formats/dataclass/compat.py b/xsdata/formats/dataclass/compat.py index 5a633a024..b51722b01 100644 --- a/xsdata/formats/dataclass/compat.py +++ b/xsdata/formats/dataclass/compat.py @@ -136,7 +136,7 @@ def get_type(self, name: str) -> ClassType: The class type instance Raises: - KeyError: If the name is not registed. + KeyError: If the name is not registered. """ return self.types[name] diff --git a/xsdata/formats/dataclass/filters.py b/xsdata/formats/dataclass/filters.py index 771140af9..f0198e201 100644 --- a/xsdata/formats/dataclass/filters.py +++ b/xsdata/formats/dataclass/filters.py @@ -771,7 +771,7 @@ def field_type(self, attr: Attr, parents: List[str]) -> str: return result - def compound_field_types(self, attr: Attr, parents: List[str]): + def compound_field_types(self, attr: Attr, parents: List[str]) -> str: """Generate type hint for a compound field. Args: