Skip to content

Commit

Permalink
docs: Cleanup a few issues (#1002)
Browse files Browse the repository at this point in the history
  • Loading branch information
tefra authored Mar 30, 2024
1 parent 2ebf999 commit 05b03b5
Show file tree
Hide file tree
Showing 14 changed files with 155 additions and 150 deletions.
9 changes: 8 additions & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
- [email protected]
types_or: [markdown]
args: [--prose-wrap=always, --print-width=88]
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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')
```
Expand All @@ -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
Expand Down
6 changes: 2 additions & 4 deletions docs/codegen/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -72,7 +70,7 @@ graph LR
<xs:element name="root" ref="RootType"/>
```

- Remove duplicate overriden types:
- Remove duplicate overridden types:

```xml
<xs:override schemaLocation="over005a.xsd">
Expand Down
2 changes: 1 addition & 1 deletion docs/codegen/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions docs/codegen/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
2 changes: 1 addition & 1 deletion docs/models/fields.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
253 changes: 127 additions & 126 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -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
4 changes: 2 additions & 2 deletions tests/integration/benchmarks/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."
),
Expand Down
2 changes: 1 addition & 1 deletion xsdata/codegen/handlers/process_mixed_content_class.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 0 additions & 2 deletions xsdata/codegen/handlers/rename_duplicate_classes.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading

0 comments on commit 05b03b5

Please sign in to comment.