8000 Lots of minor docs tweaks (#877) · ag-python/pydantic@beb5736 · GitHub
[go: up one dir, main page]
Skip to content

Commit beb5736

Browse files
dmontagusamuelcolvin
dmontagu
authored and
samuelcolvin
committed
Lots of minor docs tweaks (pydantic#877)
* Lots of minor changes * More tweaks * Remove git conflicts * suggested tweaks
1 parent 46db1ef commit beb5736

15 files changed

+446
-397
lines changed

‎docs/contributing.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
We'd love you to contribute to *pydantic*, it should be extremely simple to get started and create a Pull Request.
1+
We'd love you to contribute to *pydantic*! It should be extremely simple to get started and create a Pull Request.
22
*pydantic* is released regularly so you should see your improvements release in a matter of days or weeks.
33

44
Unless your change is trivial (typo, docs tweak etc.), please create an issue to discuss the change before
@@ -8,9 +8,9 @@ If you're looking for something to get your teeth into, check out the
88
["help wanted"](https://github.com/samuelcolvin/pydantic/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
99
label on github.
1010

11-
To make contributing as easy and fast as possible, you'll want to run tests and linting locally. Luckily since
12-
*pydantic* has few dependencies, doesn't require compiling and tests don't need access to databases etc., setting
13-
up and running tests should be very simple.
11+
To make contributing as easy and fast as possible, you'll want to run tests and linting locally. Luckily,
12+
*pydantic* has few dependencies, doesn't require compiling and tests don't need access to databases, etc.
13+
Because of this, setting up and running the tests should be very simple.
1414

1515
You'll need to have **python 3.6** or **3.7**, **virtualenv**, **git**, and **make** installed.
1616

@@ -49,4 +49,4 @@ make docs
4949
```
5050

5151
**tl;dr**: use `make format` to fix formatting, `make` to run tests and linting & `make docs`
52-
to build docs.
52+
to build the docs.

‎docs/examples/settings.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ class Settings(BaseSettings):
2525
more_settings: SubModel = SubModel()
2626

2727
class Config:
28-
env_prefix = 'my_prefix_' # defaults to no prefix, e.g. ""
28+
env_prefix = 'my_prefix_' # defaults to no prefix, i.e. ""
2929
fields = {
3030
'auth_key': {
3131
'env': 'my_auth_key',

‎docs/examples/validators_pre_item.py

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ class DemoModel(BaseModel):
55
square_numbers: List[int] = []
66
cube_numbers: List[int] = []
77

8-
@validator('*', pre=True) # '*' is same as 'cube_numbers', 'square_numbers' here
8+
# '*' is the same as 'cube_numbers', 'square_numbers' here:
9+
@validator('*', pre=True)
910
def split_str(cls, v):
1011
if isinstance(v, str):
1112
return v.split('|')
@@ -24,7 +25,8 @@ def check_squares(cls, v):
2425

2526
@validator('cube_numbers', each_item=True)
2627
def check_cubes(cls, v):
27-
# 64 ** (1 / 3) == 3.9999999999999996! this is not a good way of checking cubes
28+
# 64 ** (1 / 3) == 3.9999999999999996 (!)
29+
# this is not a good way of checking cubes
2830
assert v ** (1 / 3) % 1 == 0, f'{v} is not a cubed number'
2931
return v
3032

‎docs/index.md

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Data validation and settings management using python type hinting.
1515

1616
Define how data should be in pure, canonical python; validate it with *pydantic*.
1717

18-
[PEP 484](https://www.python.org/dev/peps/pep-0484/) introduced type hinting into python 3.5,
18+
[PEP 484](https://www.python.org/dev/peps/pep-0484/) introduced type hinting into python 3.5;
1919
[PEP 526](https://www.python.org/dev/peps/pep-0526/) extended that with syntax for variable annotation in python 3.6.
2020

2121
*pydantic* uses those annotations to validate that untrusted data takes the form you want.
@@ -31,12 +31,12 @@ _(This script is complete, it should run "as is")_
3131

3232
What's going on here:
3333

34-
* `id` is of type int; the annotation only declaration tells *pydantic* that this field is required. Strings,
35-
bytes or floats will be coerced to ints if possible, otherwise an exception would be raised.
36-
* `name` is inferred as a string from the default; it is not required as it has a default.
37-
* `signup_ts` is a datetime field which is not required (``None`` if it's not supplied), pydantic will process
38-
either a unix timestamp int (e.g. `1496498400`) or a string representing the date & time.
39-
* `friends` uses python's typing system, it is required to be a list of integers, as with `id` integer-like objects
34+
* `id` is of type int; the annotation-only declaration tells *pydantic* that this field is required. Strings,
35+
bytes or floats will be coerced to ints if possible; otherwise an exception will be raised.
36+
* `name` is inferred as a string from the provided default; because it has a default, it is not required.
37+
* `signup_ts` is a datetime field which is not required (and takes the value ``None`` if it's not supplied).
38+
*pydantic* will process either a unix timestamp int (e.g. `1496498400`) or a string representing the date & time.
39+
* `friends` uses python's typing system, and requires a list of inputs. As with `id`, integer-like objects
4040
will be converted to integers.
4141

4242
If validation fails pydantic will raise an error with F438 a breakdown of what was wrong:
@@ -55,18 +55,18 @@ outputs:
5555
So *pydantic* uses some cool new language features, but why should I actually go and use it?
5656

5757
**no brainfuck**
58-
: no new schema definition micro-language to learn. If you know python (and perhaps skim the
58+
: there's no new schema definition micro-language to learn. If you know python (and perhaps skim the
5959
[type hinting docs](https://docs.python.org/3/library/typing.html)) you know how to use *pydantic*.
6060

6161
**plays nicely with your IDE/linter/brain**
62-
: because *pydantic* data structures are just instances of classes you define; auto-completion, linting,
63-
[mypy](usage/mypy.md), IDEs (especially [PyCharm](pycharm_plugin.md)) and your intuition should
62+
: *pydantic* data structures are just instances of classes you define, so auto-completion, linting,
63+
[mypy](usage/mypy.md), IDEs (especially [PyCharm](pycharm_plugin.md)), and your intuition should
6464
all work properly with your validated data.
6565

6666
**dual use**
67-
: *pydantic's* [BaseSettings](usage/settings.md) class allows it to be used in both a "validate this request data"
68-
context and "load my system settings" context. The main difference being that system settings can have defaults
69-
changed by environment variables and more complex objects like DSNs and python objects are often required.
67+
: *pydantic's* [BaseSettings](usage/settings.md) class allows *pydantic* to be used in both a "validate this request
68+
data" context and in a "load my system settings" context. The main differences are that system settings can
69+
be read from environment variables, and more complex objects like DSNs and python objects are often required.
7070

7171
**fast**
7272
: In [benchmarks](benchmarks.md) *pydantic* is faster than all other tested libraries.
@@ -75,7 +75,7 @@ So *pydantic* uses some cool new language features, but why should I actually go
7575
: use of [recursive *pydantic* models](usage/models.md#recursive-models), `typing`'s
7676
[standard types](usage/types.md#standard-library-types) (e.g. `List`, `Tuple`, `Dict` etc.) and
7777
[validators](usage/validators.md) allow
78-
complex data schemas to be clearly and easily defined and then validated and parsed.
78+
complex data schemas to be clearly and easily defined, validated, and parsed.
7979

8080
**extensible**
8181
: *pydantic* allows [custom data types](usage/types.md#custom-data-types) to be defined or you can extend validation
@@ -96,27 +96,27 @@ Hundreds of organisations and packages are using *pydantic*, including:
9696

9797
**Microsoft**
9898
: are using *pydantic* (via FastAPI) for
99-
[numerous services](https://github.com/tiangolo/fastapi/pull/26#issuecomment-463768795) some of which are
99+
[numerous services](https://github.com/tiangolo/fastapi/pull/26#issuecomment-463768795), some of which are
100100
"getting integrated into the core Windows product and some Office products."
101101

102102
**Amazon Web Services**
103-
: are using *pydantic* in [gluon-ts](https://github.com/awslabs/gluon-ts) an open-source probabilistic time series
103+
: are using *pydantic* in [gluon-ts](https://github.com/awslabs/gluon-ts), an open-source probabilistic time series
104104
modeling library.
105105

106106
**The NSA**
107-
: are using *pydantic* in [WALKOFF](https://github.com/nsacyber/WALKOFF) an open-source automation framework.
107+
: are using *pydantic* in [WALKOFF](https://github.com/nsacyber/WALKOFF), an open-source automation framework.
108108

109109
**Uber**
110-
: are using *pydantic* in [Ludwig](https://github.com/uber/ludwig) an an open-source TensorFlow wrapper.
110+
: are using *pydantic* in [Ludwig](https://github.com/uber/ludwig), an an open-source TensorFlow wrapper.
111111

112112
**Cuenca**
113-
: a Mexican neobank that uses *pydantic* for several internal
113+
: are a Mexican neobank that uses *pydantic* for several internal
114114
tools (including API validation) and for open source projects like
115115
[stpmex](https://github.com/cuenca-mx/stpmex-python), which is used to process real-time, 24/7, inter-bank
116116
transfers in Mexico.
117117

118-
For a more comprehensive list of open-source projects using *pydantic* see
119-
[dependents on github](https://github.com/samuelcolvin/pydantic/network/dependents).
118+
For a more comprehensive list of open-source projects using *pydantic* see the
119+
[list of dependents on github](https://github.com/samuelcolvin/pydantic/network/dependents).
120120

121121
<script>
122122
{!./redirects.js!}

‎docs/install.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
1-
2-
Just:
1+
Installation is as simple as:
32

43
```py
54
pip install pydantic
65
```
76

87
*pydantic* has no required dependencies except python 3.6 or 3.7 (and the dataclasses package in python 3.6).
9-< 1C6A /span>
If you've got python 3.6 and `pip` installed - you're good to go.
8+
If you've got python 3.6 and `pip` installed, you're good to go.
109

1110
Pydantic is also available on [conda](https://www.anaconda.com) under the [conda-forge](https://conda-forge.org)
1211
channel:
@@ -17,9 +16,9 @@ conda install pydantic -c conda-forge
1716

1817
*pydantic* can optionally be compiled with [cython](https://cython.org/) which should give a 30-50% performance
1918
improvement. `manylinux` binaries exist for python 3.6 and 3.7, so if you're installing from PyPI on linux, you
20-
should get *pydantic* compiled with no extra work. If you're installing manually, install `cython` before installing
21-
*pydantic* and you should get *pydandic* compiled. Compilation with cython
22-
[is not](https://github.com/samuelcolvin/pydantic/issues/555) tested on windows or mac.
19+
should get a compiled version of *pydantic* with no extra work. If you're installing manually, install `cython`
20+
before installing *pydantic* and compilation should happen automatically. Compilation with cython
21+
[is not tested](https://github.com/samuelcolvin/pydantic/issues/555) on windows or mac.
2322

2423
To test if *pydantic* is compiled run:
2524

@@ -40,4 +39,4 @@ pip install pydantic[typing_extensions]
4039
pip install pydantic[email,typing_extensions]
4140
```
4241

43-
Of course you can also install these requirements manually with `pip install ...`.
42+
Of course, you can also install these requirements manually with `pip install ...`.

‎docs/usage/dataclasses.md

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,26 +9,27 @@ Dataclasses work in python 3.6 using the [dataclasses backport package](https://
99
_(This script is complete, it should run "as is")_
1010

1111
!!! note
12-
Keep in mind that `pydantic.dataclasses.dataclass` is a drop in replacement for `dataclasses.dataclass`
13-
with validation, not a replacement for `pydantic.BaseModel`. There are cases where subclassing
12+
Keep in mind that `pydantic.dataclasses.dataclass` is a drop-in replacement for `dataclasses.dataclass`
13+
with validation, **not** a replacement for `pydantic.BaseModel`. There are cases where subclassing
1414
`pydantic.BaseModel` is the better choice.
1515

1616
For more information and discussion see
1717
[samuelcolvin/pydantic#710](https://github.com/samuelcolvin/pydantic/issues/710).
1818

19-
You can use all the standard pydantic field types and the resulting dataclass will be identical to the one
19+
You can use all the standard pydantic field types, and the resulting dataclass will be identical to the one
2020
created by the standard library `dataclass` decorator.
2121

2222
`pydantic.dataclasses.dataclass`'s arguments are the same as the standard decorator, except one extra
23-
key word argument `config` which has the same meaning as [Config](model_config.md).
23+
keyword argument `config` which has the same meaning as [Config](model_config.md).
2424

2525
!!! note
26-
As a side effect of getting pydantic dataclasses to play nicely with mypy the `config` argument will show
27-
as invalid in IDEs and mypy, use `@dataclass(..., config=Config) # type: ignore` as a workaround.
26+
As a side effect of getting pydantic dataclasses to play nicely with mypy, the `config` argument will show
27+
as invalid in IDEs and mypy. Use `@dataclass(..., config=Config) # type: ignore` as a workaround.
2828

29-
See [python/mypy#6239](https://github.com/python/mypy/issues/6239) for an explanation of why this is.
29+
See [python/mypy#6239](https://github.com/python/mypy/issues/6239) for an explanation of this issue.
3030

31-
For information on validators with dataclasses see [dataclass validators](validators.md#dataclass-validators)
31+
For more information about combining validators with dataclasses, see
32+
[dataclass validators](validators.md#dataclass-validators).
3233

3334
## Nested dataclasses
3435

@@ -39,13 +40,13 @@ Nested dataclasses are supported both in dataclasses and normal models.
3940
```
4041
_(This script is complete, it should run "as is")_
4142

42-
Dataclasses attributes can be populated by tuples, dictionaries or instances of that dataclass.
43+
Dataclasses attributes can be populated by tuples, dictionaries or instances of the dataclass itself.
4344

4445
## Initialize hooks
4546

46-
When you initialize a dataclass, it is possible to execute code after validation
47-
with the help of `__post_init_post_parse__`. This is not the same as `__post_init__` which executes
48-
code before validation.
47+
When you initialize a dataclass, it is possible to execute code *after* validation
48+
with the help of `__post_init_post_parse__`. This is not the same as `__post_init__`, which executes
49+
code *before* validation.
4950

5051
```py
5152
{!./examples/ex_post_init_post_parse.py!}
@@ -59,4 +60,3 @@ Since version **v1.0**, any fields annotated with `dataclasses.InitVar` are pass
5960
{!./examples/ex_post_init_post_parse_initvars.py!}
6061
```
6162
_(This script is complete, it should run "as is")_
62-

0 commit comments

Comments
 (0)
0