release notes for v1 (pydantic#918)

* release notes for v1

* uprev and tweaks

* Apply suggestions from code review

Co-Authored-By: dmontagu <[email protected]>

* tweak notes, add back link to old docs

* build changelog

Author: samuelcolvin

HISTORY.md

@@ -1,3 +1,31 @@
+## v1.0 (2019-10-23)
+
+* **Breaking Change:** deprecate the `Model.fields` property, use `Model.__fields__` instead, #883 by @samuelcolvin
+* **Breaking Change:** Change the precedence of aliases so child model aliases override parent aliases, 
+  including using `alias_generator`, #904 by @samuelcolvin
+* **Breaking change:** Rename `skip_defaults` to `exclude_unset`, and add ability to exclude actual defaults, #915 by @dmontagu
+* Add `**kwargs` to `pydantic.main.ModelMetaclass.__new__` so `__init_subclass__` can take custom parameters on extended 
+  `BaseModel` classes, #867 by @retnikt
+* Fix field of a type that has a default value, #880 by @koxudaxi
+* Use `FutureWarning` instead of `DeprecationWarning` when `alias` instead of `env` is used for settings models, #881 by @samuelcolvin
+* Fix issue with `BaseSettings` inheritance and `alias` getting set to `None`, #882 by @samuelcolvin
+* Modify `__repr__` and `__str__` methods to be consistent across all public classes, add `__pretty__` to support
+  python-devtools, #884 by @samuelcolvin
+* deprecation warning for `case_insensitive` on `BaseSettings` config, #885 by @samuelcolvin
+* For `BaseSettings` merge environment variables and in-code values recursively, as long as they create a valid object
+  when merged together, to allow splitting init arguments, #888 by @idmitrievsky
+* change secret types example, #890 by @ashears
+* Change the signature of `Model.construct()` to be more user-friendly, document `construct()` usage, #898 by @samuelcolvin
+* Add example for the `construct()` method, #907 by @ashears
+* Improve use of `Field` constraints on complex types, raise an error if constraints are not enforceable,
+  also support tuples with an ellipsis `Tuple[X, ...]`, `Sequence` and `FrozenSet` in schema, #909 by @samuelcolvin
+* update docs for bool missing valid value, #911 by @trim21
+* Better `str`/`repr` logic for `ModelField`, #912 by @samuelcolvin
+* Fix `ConstrainedList`, update schema generation to reflect `min_items` and `max_items` `Field()` arguments, #917 by @samuelcolvin
+* Allow abstracts sets (eg. dict keys) in the `include` and `exclude` arguments of `dict()`, #921 by @samuelcolvin
+* Fix JSON serialization errors on `ValidationError.json()` by using `pydantic_encoder`, #922 by @samuelcolvin
+* Clarify usage of `remove_untouched`, improve error message for types with no validators, #926 by @retnikt
+
 ## v1.0b2 (2019-10-07)
 
 * Mark `StrictBool` typecheck as `bool` to allow for default values without mypy errors, #690 by @dmontagu

changes/867-retnikt.md

@@ -11,7 +11,7 @@ class User(BaseModel):
 external_data = {
     'id': '123',
     'signup_ts': '2019-06-01 12:22',
-    'friends': [1, '2', 3.1415]
+    'friends': [1, 2, '3']
 }
 user = User(**external_data)
 print(user.id)

changes/880-koxudaxi.md

@@ -7,20 +7,15 @@
 
 {!.version.md!}
 
-!!! note
-    These docs refer to Version 1 of *pydantic* which is as-yet unreleased. **v0.32** docs are available
-    [here](https://5d584fcca7c9b70007d1c997--pydantic-docs.netlify.com).
+Data validation and settings management using python type annotations.
 
-Data validation and settings management using python type hinting.
+*pydantic* enforces type hints at runtime, and provides user friendly errors when data is invalid.
 
 Define how data should be in pure, canonical python; validate it with *pydantic*.
 
-[PEP 484](https://www.python.org/dev/peps/pep-0484/) introduced type hinting into python 3.5;
-[PEP 526](https://www.python.org/dev/peps/pep-0526/) extended that with syntax for variable annotation in python 3.6.
-
-*pydantic* uses those annotations to validate that untrusted data takes the form you want.
-
-There's also support for an extension to [dataclasses](usage/dataclasses.md) where the input data is validated.
+!!! note "Version 0.32 Documentation"
+    This documentation refers to Version 1 of *pydantic* which has just been released, **v0.32.2** 
+    (the previous release) docs are available [here](https://5d584fcca7c9b70007d1c997--pydantic-docs.netlify.com).
 
 ## Example
 
@@ -51,17 +46,13 @@ outputs:
 
 ## Rationale
 
-
 So *pydantic* uses some cool new language features, but why should I actually go and use it?
 
-**no brainfuck**
-: there's no new schema definition micro-language to learn. If you know python (and perhaps skim the
-  [type hinting docs](https://docs.python.org/3/library/typing.html)) you know how to use *pydantic*.
-
 **plays nicely with your IDE/linter/brain**
-: *pydantic* data structures are just instances of classes you define, so auto-completion, linting,
-  [mypy](usage/mypy.md), IDEs (especially [PyCharm](pycharm_plugin.md)), and your intuition should 
-  all work properly with your validated data.
+: There's no new schema definition micro-language to learn. If you know how to use python type hints, 
+  you know how to use *pydantic*. Data structures are just instances of classes you define with type annotations, 
+  so auto-completion, linting, [mypy](usage/mypy.md), IDEs (especially [PyCharm](pycharm_plugin.md)), 
+  and your intuition should all work properly with your validated data.
 
 **dual use**
 : *pydantic's* [BaseSettings](usage/settings.md) class allows *pydantic* to be used in both a "validate this request
@@ -80,7 +71,11 @@ So *pydantic* uses some cool new language features, but why should I actually go
 **extensible**
 : *pydantic* allows [custom data types](usage/types.md#custom-data-types) to be defined or you can extend validation 
   with methods on a model decorated with the [`validator`](usage/validators.md) decorator.
-
+  
+**dataclasses integration**
+: As well as `BaseModel`, *pydantic* provides
+  a [`dataclass`](usage/dataclasses.md) decorator which creates (almost) vanilla python dataclasses with input
+  data parsing and validation.
 
 ## Using Pydantic
 

changes/881-samuelcolvin.md

@@ -121,6 +121,7 @@ For self-referencing models, see [postponed annotations](postponed_annotations.m
 Pydantic models can be created from arbitrary class instances to support models that map to ORM objects.
 
 To do this:
+
 1. The [Config](model_config.md) property `orm_mode` must be set to `True`.
 2. The special constructor `from_orm` must be used to create the model instance.
 
@@ -380,10 +381,10 @@ _(This script is complete, it should run "as is")_
 
 !!! warning
     As demonstrated by the example above, combining the use of annotated and non-annotated fields
-    in the same model can result in surprising field orderings. (This is due to limitations of python.)
+    in the same model can result in surprising field orderings. (This is due to limitations of python)
 
     Therefore, **we recommend adding type annotations to all fields**, even when a default value
-    would determine the type by itself.
+    would determine the type by itself to guarentee field order is preserved.
 
 ## Required fields
 

changes/882-samuelcolvin.md

@@ -0,0 +1,76 @@
+After 2.5 years of development with contributions from over 80 people and 62 releases, *pydantic* has reached
+version 1!
+
+While the fundamentals of *pydantic* have remained unchanged since the previous release 
+[v0.32.2](changelog.md#v0322-2019-08-17) (indeed, since *pydantic* began in early 2017); 
+a number of things have changed which you may wish to be aware of while migrating to Version 1.
+
+Below is a list of significant changes, for a full list of changes see release notes for 
+[v1.0b1](changelog.md#v10b1-2019-10-01), [v1.0b2](changelog.md#v10b2-2019-10-07), 
+and [v1.0](changelog.md#v10-2019-10-23).
+
+## What's new in pydantic v1
+
+### Root validators
+
+A new decorator [`root_validator`](usage/validators.md#root-validators) has been added to allow validation of entire
+models.
+
+### Custom JSON encoding/decoding
+
+There are new `Config` settings to allow 
+[Custom JSON (de)serialisation](usage/exporting_models.md#custom-json-deserialisation). This can allow alternative
+JSON implementations to be used with significantly improved performance.
+
+### Boolean parsing
+
+The logic for [parsing and validating boolean values](usage/types.md#booleans) has been overhauled to only allow
+a defined set of values rather than allowing any value as it used to. 
+
+### URL parsing
+
+The logic for parsing URLs (and related objects like DSNs) has been completely re-written to provide more useful
+error messages, greater simplicity and more flexibility.
+
+### Performance improvements
+
+Some less "clever" error handling and cleanup of how errors are wrapped (together with many other small changes)
+has improved the performance of *pydantic* by ~25%, see 
+[samuelcolvin/pydantic#819](https://github.com/samuelcolvin/pydantic/pull/819).
+
+### ORM mode improvements
+
+There are improvements to [`GetterDict`](usage/models.md#orm-mode-aka-arbitrary-class-instances) to make ORM mode
+easier to use and work with root validators, see 
+[samuelcolvin/pydantic#822](https://github.com/samuelcolvin/pydantic/pull/822).
+
+### Settings improvements
+
+There are a number of changes to how [`BaseSettings`](usage/settings.md) works:
+
+* `case_insensitive` has been renamed to `case_sensitive` and the default has changed to `case_sensitive = False`
+* the default for `env_prefix` has changed to an empty string, i.e. by default there's no prefix for environment
+  variable lookups
+* aliases are no longer used when looking up environment variables, instead there's a new `env` setting for `Field()` or 
+  in `Config.fields`.
+
+### Improvements to field ordering
+
+There are some subtle changes to the ordering of fields, see [Model field ordering](usage/models.md#field-ordering)
+for more details.
+
+### Schema renamed to Field
+
+The function used for providing extra information about fields has been renamed from `Schema` to `Field`. The
+new name makes more sense since the method can be used to provide any sort of information and change the behaviour
+of the field, as well as add attributes which are used while [generating a model schema](usage/schema.md).
+
+### Improved repr methods and devtools integration 
+
+The `__repr__` and `__str__` method of models as well as most other public classes in *pydantic* have been altered
+to be consistent and informative. There's also new [integration with python-devtools](usage/devtools.md).
+
+### Field constraints checks
+
+Constraints added to `Field()` which are not enforced now cause an error when a model is created, see
+[Unenforced Field constraints](usage/schema.md#unenforced-field-constraints) for more details and work-arounds.

changes/883-samuelcolvin.md

@@ -1,4 +1,4 @@
-site_name: Pydantic
+site_name: pydantic
 site_description: Data validation and settings management using python 3.6 type hinting
 strict: true
 site_url: https://pydantic-docs.helpmanual.io/
@@ -25,6 +25,7 @@ extra_javascript:
 nav:
 - Overview: index.md
 - install.md
+- 'Version 1 release notes': version_1_release_notes.md
 - Usage:
   - usage/models.md
   - 'Field Types': usage/types.md
@@ -37,7 +38,7 @@ nav:
   - usage/postponed_annotations.md
   - 'Usage with mypy': usage/mypy.md
   - 'Usage with devtools': usage/devtools.md
-- Contributing to Pydantic: contributing.md
+- Contributing to pydantic: contributing.md
 - benchmarks.md
 - 'PyCharm plugin': pycharm_plugin.md
 - changelog.md

changes/884-samuelcolvin.md

@@ -2,4 +2,4 @@
 
 __all__ = ['VERSION']
 
-VERSION = StrictVersion('1.0b2')
+VERSION = StrictVersion('1.0')