Skip to content

Commit 8e9b1e8

Browse files
KludexKludex
authored
Revert "Refactor documentation" (#96)
1 parent 006a6f2 commit 8e9b1e8

19 files changed

+528
-258
lines changed

‎docs/color_types.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
2+
`Color` parses HTML and CSS colors.
3+
4+
You can use the `Color` data type for storing colors as per
5+
[CSS3 specification](http://www.w3.org/TR/css3-color/#svg-color). Colors can be defined via:
6+
7+
- [name](http://www.w3.org/TR/SVG11/types.html#ColorKeywords) (e.g. `"Black"`, `"azure"`)
8+
- [hexadecimal value](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet)
9+
(e.g. `"0x000"`, `"#FFFFFF"`, `"7fffd4"`)
10+
- RGB/RGBA tuples (e.g. `(255, 255, 255)`, `(255, 255, 255, 0.5)`)
11+
- [RGB/RGBA strings](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#RGB_colors)
12+
(e.g. `"rgb(255, 255, 255)"`, `"rgba(255, 255, 255, 0.5)"`)
13+
- [HSL strings](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#HSL_colors)
14+
(e.g. `"hsl(270, 60%, 70%)"`, `"hsl(270, 60%, 70%, .5)"`)
15+
16+
```py
17+
from pydantic import BaseModel, ValidationError
18+
19+
from pydantic_extra_types import Color
20+
21+
c = Color('ff00ff')
22+
print(c.as_named())
23+
#> magenta
24+
print(c.as_hex())
25+
#> #f0f
26+
c2 = Color('green')
27+
print(c2.as_rgb_tuple())
28+
#> (0, 128, 0)
29+
print(c2.original())
30+
#> green
31+
print(repr(Color('hsl(180, 100%, 50%)')))
32+
#> Color('cyan', rgb=(0, 255, 255))
33+
34+
35+
class Model(BaseModel):
36+
color: Color
37+
38+
39+
print(Model(color='purple'))
40+
#> color=Color('purple', rgb=(128, 0, 128))
41+
try:
42+
Model(color='hello')
43+
except ValidationError as e:
44+
print(e)
45+
"""
46+
1 validation error for Model
47+
color
48+
value is not a valid color: string not recognised as a valid color [type=color_error, input_value='hello', input_type=str]
49+
"""
50+
```
51+
52+
`Color` has the following methods:
53+
54+
**`original`**
55+
: the original string or tuple passed to `Color`
56+
57+
**`as_named`**
58+
: returns a named CSS3 color; fails if the alpha channel is set or no such color exists unless
59+
`fallback=True` is supplied, in which case it falls back to `as_hex`
60+
61+
**`as_hex`**
62+
: returns a string in the format `#fff` or `#ffffff`; will contain 4 (or 8) hex values if the alpha channel is set,
63+
e.g. `#7f33cc26`
64+
65+
**`as_rgb`**
66+
: returns a string in the format `rgb(<red>, <green>, <blue>)`, or `rgba(<red>, <green>, <blue>, <alpha>)`
67+
if the alpha channel is set
68+
69+
**`as_rgb_tuple`**
70+
: returns a 3- or 4-tuple in RGB(a) format. The `alpha` keyword argument can be used to define whether
71+
the alpha channel should be included;
72+
options: `True` - always include, `False` - never include, `None` (default) - include if set
73+
74+
**`as_hsl`**
75+
: string in the format `hsl(<hue deg>, <saturation %>, <lightness %>)`
76+
or `hsl(<hue deg>, <saturation %>, <lightness %>, <alpha>)` if the alpha channel is set
77+
78+
**`as_hsl_tuple`**
79+
: returns a 3- or 4-tuple in HSL(a) format. The `alpha` keyword argument can be used to define whether
80+
the alpha channel should be included;
81+
options: `True` - always include, `False` - never include, `None` (the default) - include if set
82+
83+
The `__str__` method for `Color` returns `self.as_named(fallback=True)`.
84+
85+
!!! note
86+
The `as_hsl*` refer to hue, saturation, lightness "HSL" as used in html and most of the world, **not**
87+
"HLS" as used in Python's `colorsys`.

‎docs/coordinate.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
2+
Coordinate parses Latitude and Longitude.
3+
4+
You can use the `Coordinate` data type for storing coordinates. Coordinates can be defined using one of the following formats:
5+
6+
1. Tuple format: `(Latitude, Longitude)`. For example: `(41.40338, 2.17403)`.
7+
2. `Coordinate` instance format: `Coordinate(latitude=Latitude, longitude=Longitude)`. For example: `Coordinate(latitude=41.40338, longitude=2.17403)`.
8+
9+
The `Latitude` class and `Longitude` class, which are used to represent latitude and longitude, respectively, enforce the following valid ranges for their values:
10+
11+
- `Latitude`: The latitude value should be between -90 and 90, inclusive.
12+
- `Longitude`: The longitude value should be between -180 and 180, inclusive.
13+
14+
```py
15+
from pydantic import BaseModel
16+
17+
from pydantic_extra_types.coordinate import Longitude, Latitude, Coordinate
18+
19+
20+
class Lat(BaseModel):
21+
lat: Latitude
22+
23+
24+
class Lng(BaseModel):
25+
lng: Longitude
26+
27+
28+
class Coord(BaseModel):
29+
coord: Coordinate
30+
31+
32+
lat = Lat(
33+
lat='90.0',
34+
)
35+
36+
lng = Lng(
37+
long='180.0'
38+
)
39+
40+
coord = Coord(
41+
coord=('90.0', '180.0')
42+
)
43+
print(lat.lat)
44+
# > 90.0
45+
print(lng.lng)
46+
# > 180.0
47+
print(coord.coord)
48+
# > 90.0,180.0
49+
```

‎docs/extra/terminal.css‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
.terminal {
2+
background: #300a24;
3+
border-radius: 4px;
4+
padding: 5px 10px;
5+
}
6+
7+
pre.terminal-content {
8+
display: inline-block;
9+
line-height: 1.3 !important;
10+
white-space: pre-wrap;
11+
word-wrap: break-word;
12+
background: #300a24 !important;
13+
color: #d0d0d0 !important;
14+
}
15+
16+
.ansi2 {
17+
font-weight: lighter;
18+
}
19+
.ansi3 {
20+
font-style: italic;
21+
}
22+
.ansi32 {
23+
color: #00aa00;
24+
}
25+
.ansi34 {
26+
color: #5656fe;
27+
}
28+
.ansi35 {
29+
color: #E850A8;
30+
}
31+
.ansi38-1 {
32+
color: #cf0000;
33+
}
34+
.ansi38-5 {
35+
color: #E850A8;
36+
}
37+
.ansi38-68 {
38+
color: #2a54a8;
39+
}

‎docs/extra/tweaks.css‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
.sponsors {
2+
display: flex;
3+
justify-content: center;
4+
flex-wrap: wrap;
5+
align-items: center;
6+
margin: 1rem 0;
7+
}
8+
9+
.sponsors > div {
10+
text-align: center;
11+
width: 33%;
12+
padding-bottom: 20px;
13+
}
14+
15+
.sponsors span {
16+
display: block;
17+
}
18+
19+
@media screen and (max-width: 599px) {
20+
.sponsors span {
21+
display: none;
22+
}
23+
}
24+
25+
.sponsors img {
26+
width: 65%;
27+
border-radius: 5px;
28+
}
29+
30+
/*blog post*/
31+
aside.blog {
32+
display: flex;
33+
align-items: center;
34+
}
35+
36+
aside.blog img {
37+
width: 50px;
38+
height: 50px;
39+
border-radius: 25px;
40+
margin-right: 20px;
41+
}
42+
43+
/* Define the company grid layout */
44+
45+
#grid-container {
46+
width: 100%;
47+
text-align: center;
48+
}
49+
50+
#company-grid {
51+
display: inline-block;
52+
margin: 0 auto;
53+
gap: 10px;
54+
align-content: center;
55+
justify-content: center;
56+
grid-auto-flow: column;
57+
}
58+
59+
[data-md-color-scheme="slate"] #company-grid {
60+
background-color: #ffffff;
61+
border-radius: .5rem;
62+
}
63+
64+
.tile {
65+
display: flex;
66+
text-align: center;
67+
width: 120px;
68+
height: 120px;
69+
display: inline-block;
70+
margin: 10px;
71+
padding: 5px;
72+
border-radius: .5rem;
73+
}
74+
75+
.tile img {
76+
width: 100px;
77+
}

‎docs/favicon.png‎

891 Bytes
Loading

‎docs/logo-white.svg‎

Lines changed: 3 additions & 0 deletions
Loading

‎docs/mac_address.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
2+
The `MacAddress` type validates [MAC address](https://en.wikipedia.org/wiki/MAC_address) (such as a network card).
3+
4+
```py
5+
from pydantic import BaseModel
6+
7+
from pydantic_extra_types.mac_address import MacAddress
8+
9+
10+
class Network(BaseModel):
11+
mac_address: MacAddress
12+
13+
14+
network = Network(
15+
mac_address='00:00:5e:00:53:01',
16+
)
17+
18+
print(network.mac_address)
19+
# > 00:00:5e:00:53:01
20+
```
21+
22+
The algorithm used to validate the MAC address `IEEE` `802` `MAC-48`, `EUI-48`, `EUI-64`, or a `20-octet`.

‎docs/payment_cards.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
2+
The `PaymentCardNumber` type validates [payment cards]
3+
(such as a debit or credit card).
4+
5+
```py
6+
from datetime import date
7+
8+
from pydantic import BaseModel, constr
9+
10+
from pydantic_extra_types.payment import PaymentCardBrand, PaymentCardNumber
11+
12+
13+
class Card(BaseModel):
14+
name: constr(strip_whitespace=True, min_length=1)
15+
number: PaymentCardNumber
16+
exp: date
17+
18+
@property
19+
def brand(self) -> PaymentCardBrand:
20+
return self.number.brand
21+
22+
@property
23+
def expired(self) -> bool:
24+
return self.exp < date.today()
25+
26+
27+
card = Card(
28+
name='Georg Wilhelm Friedrich Hegel',
29+
number='4000000000000002',
30+
exp=date(2023, 9, 30),
31+
)
32+
33+
assert card.number.brand == PaymentCardBrand.visa
34+
assert card.number.bin == '400000'
35+
assert card.number.last4 == '0002'
36+
assert card.number.masked == '400000******0002'
37+
```
38+
39+
`PaymentCardBrand` can be one of the following based on the BIN:
40+
41+
* `PaymentCardBrand.amex`
42+
* `PaymentCardBrand.mastercard`
43+
* `PaymentCardBrand.visa`
44+
* `PaymentCardBrand.other`
45+
46+
The actual validation verifies the card number is:
47+
48+
* a `str` of only digits
49+
* [luhn](https://en.wikipedia.org/wiki/Luhn_algorithm) valid
50+
* the correct length based on the BIN, if Amex, Mastercard or Visa, and between
51+
12 and 19 digits for all other brands
52+
53+
54+
[payment cards]: https://en.wikipedia.org/wiki/Payment_card

‎docs/phone_numbers.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
2+
The `PhoneNumber` type validates phone numbers.
3+
4+
This class depends on the [phonenumbers] package, which is a Python port of Google's [libphonenumber].
5+
6+
```py
7+
from pydantic import BaseModel
8+
9+
from pydantic_extra_types.phone_numbers import PhoneNumber
10+
11+
12+
class User(BaseModel):
13+
name: str
14+
phone_number: PhoneNumber
15+
16+
17+
user = User(name='John', phone_number='+447911123456')
18+
print(user.phone_number) # (1)!
19+
#> tel:+44-7911-123456
20+
```
21+
22+
1. The phone format used is described on the [RFC3966].
23+
24+
25+
[phonenumbers]: https://pypi.org/project/phonenumbers/
26+
[libphonenumber]: https://github.com/google/libphonenumber/
27+
[RFC3966]: https://tools.ietf.org/html/rfc3966

‎docs/routing_numbers.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
2+
The `ABARoutingNumber` type validates [ABA routing transit numbers].
3+
4+
5+
```py
6+
from pydantic import BaseModel
7+
8+
from pydantic_extra_types.routing_number import ABARoutingNumber
9+
10+
11+
class BankAccount(BaseModel):
12+
name: str
13+
routing_number: ABARoutingNumber
14+
account_number: str
15+
16+
17+
account = BankAccount(
18+
name="John",
19+
routing_number="122105155",
20+
account_number="123456789",
21+
)
22+
23+
print(account.routing_number)
24+
# > 122105155
25+
```
26+
27+
The algorithm used to validate the routing number is described on this [section of the Wikipedia page].
28+
29+
30+
[ABA routing transit numbers]: https://en.wikipedia.org/wiki/ABA_routing_transit_number
31+
[section of the Wikipedia page]: https://en.wikipedia.org/wiki/ABA_routing_transit_number#Check_digit

0 commit comments

Comments
 (0)