Skip to content

Commit

Permalink
Update README with blank_none information
Browse files Browse the repository at this point in the history
  • Loading branch information
@d3-steichman
d3-steichman committed Oct 7, 2024
1 parent cb5221f commit 3f50227
Showing 1 changed file with 32 additions and 24 deletions.
56 changes: 32 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -142,26 +142,27 @@ These can be used in tandem to describe a parameter to validate: `parameter_name
### Validation with arguments to Parameter
Validation beyond type-checking can be done by passing arguments into the constructor of the `Parameter` subclass. The arguments available for use on each type hint are:

| Parameter Name | Type of Argument | Effective On Types | Description |
|-------------------|--------------------------------------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | any | All, except in `Route` | Specifies the default value for the field, makes non-Optional fields not required |
| `min_str_length` | `int` | `str` | Specifies the minimum character length for a string input |
| `max_str_length` | `int` | `str` | Specifies the maximum character length for a string input |
| `min_list_length` | `int` | `list` | Specifies the minimum number of elements in a list |
| `max_list_length` | `int` | `list` | Specifies the maximum number of elements in a list |
| `min_int` | `int` | `int` | Specifies the minimum number for an integer input |
| `max_int` | `int` | `int` | Specifies the maximum number for an integer input |
| `whitelist` | `str` | `str` | A string containing allowed characters for the value |
| `blacklist` | `str` | `str` | A string containing forbidden characters for the value |
| `pattern` | `str` | `str` | A regex pattern to test for string matches |
| `func` | `Callable[Any] -> Union[bool, tuple[bool, str]]` | All | A function containing a fully customized logic to validate the value. See the [custom validation function](#custom-validation-function) below for usage |
| `datetime_format` | `str` | `datetime.datetime` | Python datetime format string datetime format string ([datetime format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)) |
| `comment` | `str` | All | A string to display as the argument description in any generated documentation |
| `alias` | `str` | All but `FileStorage` | An expected parameter name to receive instead of the function name. |
| `json_schema` | `dict` | `dict` | An expected [JSON Schema](https://json-schema.org) which the dict input must conform to |
| `content_types` | `list[str]` | `FileStorage` | Allowed `Content-Type`s |
| `min_length` | `int` | `FileStorage` | Minimum `Content-Length` for a file |
| `max_length` | `int` | `FileStorage` | Maximum `Content-Length` for a file |
| Parameter Name | Type of Argument | Effective On Types | Description |
|-------------------|--------------------------------------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | any | All, except in `Route` | Specifies the default value for the field, makes non-Optional fields not required |
| `min_str_length` | `int` | `str` | Specifies the minimum character length for a string input |
| `max_str_length` | `int` | `str` | Specifies the maximum character length for a string input |
| `min_list_length` | `int` | `list` | Specifies the minimum number of elements in a list |
| `max_list_length` | `int` | `list` | Specifies the maximum number of elements in a list |
| `min_int` | `int` | `int` | Specifies the minimum number for an integer input |
| `max_int` | `int` | `int` | Specifies the maximum number for an integer input |
| `whitelist` | `str` | `str` | A string containing allowed characters for the value |
| `blacklist` | `str` | `str` | A string containing forbidden characters for the value |
| `pattern` | `str` | `str` | A regex pattern to test for string matches |
| `func` | `Callable[Any] -> Union[bool, tuple[bool, str]]` | All | A function containing a fully customized logic to validate the value. See the [custom validation function](#custom-validation-function) below for usage |
| `datetime_format` | `str` | `datetime.datetime` | Python datetime format string datetime format string ([datetime format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)) |
| `comment` | `str` | All | A string to display as the argument description in any generated documentation |
| `alias` | `str` | All but `FileStorage` | An expected parameter name to receive instead of the function name. |
| `json_schema` | `dict` | `dict` | An expected [JSON Schema](https://json-schema.org) which the dict input must conform to |
| `content_types` | `list[str]` | `FileStorage` | Allowed `Content-Type`s |
| `min_length` | `int` | `FileStorage` | Minimum `Content-Length` for a file |
| `max_length` | `int` | `FileStorage` | Maximum `Content-Length` for a file |
| `blank_none` | `bool` | `Optional[str]` | If `True`, an empty string will be converted to `None`, defaults to configured `FPV_BLANK_NONE`, see [Validation Behavior Configuration](#validation-behavior-configuration) for more |

These validators are passed into the `Parameter` subclass in the route function, such as:
* `username: str = Json(default="defaultusername", min_length=5)`
Expand All @@ -183,18 +184,25 @@ def is_odd(val: int):
return val % 2 != 0, "val must be odd"
```

### API Documentation
Using the data provided through parameters, docstrings, and Flask route registrations, Flask Parameter Validation can generate API Documentation in various formats.
To make this easy to use, it comes with a `Blueprint` and the output and configuration options below:
### Configuration Options

#### Format
#### API Documentation Configuration
* `FPV_DOCS_SITE_NAME: str`: Your site's name, to be displayed in the page title, default: `Site`
* `FPV_DOCS_CUSTOM_BLOCKS: array`: An array of dicts to display as cards at the top of your documentation, with the (optional) keys:
* `title: Optional[str]`: The title of the card
* `body: Optional[str] (HTML allowed)`: The body of the card
* `order: int`: The order in which to display this card (out of the other custom cards)
* `FPV_DOCS_DEFAULT_THEME: str`: The default theme to display in the generated webpage

See the [API Documentation](#api-documentation) below for other information on API Documentation generation

#### Validation Behavior Configuration
* `FPV_BLANK_NONE: bool`: Globally override the default `blank_none` behavior for routes in your application, defaults to `False` if unset

### API Documentation
Using the data provided through parameters, docstrings, and Flask route registrations, Flask Parameter Validation can generate API Documentation in various formats.
To make this easy to use, it comes with a `Blueprint` and the output shown below and configuration options [above](#api-documentation-configuration):

#### Included Blueprint
The documentation blueprint can be added using the following code:
```py
Expand Down

0 comments on commit 3f50227

Please sign in to comment.