Revert "Refactor documentation" (#96)

docs/color_types.md

@@ -0,0 +1,87 @@
+
+`Color` parses HTML and CSS colors.
+
+You can use the `Color` data type for storing colors as per
+[CSS3 specification](http://www.w3.org/TR/css3-color/#svg-color). Colors can be defined via:
+
+- [name](http://www.w3.org/TR/SVG11/types.html#ColorKeywords) (e.g. `"Black"`, `"azure"`)
+- [hexadecimal value](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet)
+  (e.g. `"0x000"`, `"#FFFFFF"`, `"7fffd4"`)
+- RGB/RGBA tuples (e.g. `(255, 255, 255)`, `(255, 255, 255, 0.5)`)
+- [RGB/RGBA strings](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#RGB_colors)
+  (e.g. `"rgb(255, 255, 255)"`, `"rgba(255, 255, 255, 0.5)"`)
+- [HSL strings](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#HSL_colors)
+  (e.g. `"hsl(270, 60%, 70%)"`, `"hsl(270, 60%, 70%, .5)"`)
+
+```py
+from pydantic import BaseModel, ValidationError
+
+from pydantic_extra_types import Color
+
+c = Color('ff00ff')
+print(c.as_named())
+#> magenta
+print(c.as_hex())
+#> #f0f
+c2 = Color('green')
+print(c2.as_rgb_tuple())
+#> (0, 128, 0)
+print(c2.original())
+#> green
+print(repr(Color('hsl(180, 100%, 50%)')))
+#> Color('cyan', rgb=(0, 255, 255))
+
+
+class Model(BaseModel):
+    color: Color
+
+
+print(Model(color='purple'))
+#> color=Color('purple', rgb=(128, 0, 128))
+try:
+    Model(color='hello')
+except ValidationError as e:
+    print(e)
+    """
+    1 validation error for Model
+    color
+      value is not a valid color: string not recognised as a valid color [type=color_error, input_value='hello', input_type=str]
+    """
+```
+
+`Color` has the following methods:
+
+**`original`**
+: the original string or tuple passed to `Color`
+
+**`as_named`**
+: returns a named CSS3 color; fails if the alpha channel is set or no such color exists unless
+  `fallback=True` is supplied, in which case it falls back to `as_hex`
+
+**`as_hex`**
+: returns a string in the format `#fff` or `#ffffff`; will contain 4 (or 8) hex values if the alpha channel is set,
+  e.g. `#7f33cc26`
+
+**`as_rgb`**
+: returns a string in the format `rgb(<red>, <green>, <blue>)`, or `rgba(<red>, <green>, <blue>, <alpha>)`
+  if the alpha channel is set
+
+**`as_rgb_tuple`**
+: returns a 3- or 4-tuple in RGB(a) format. The `alpha` keyword argument can be used to define whether
+  the alpha channel should be included;
+  options: `True` - always include, `False` - never include, `None` (default) - include if set
+
+**`as_hsl`**
+: string in the format `hsl(<hue deg>, <saturation %>, <lightness %>)`
+  or `hsl(<hue deg>, <saturation %>, <lightness %>, <alpha>)` if the alpha channel is set
+
+**`as_hsl_tuple`**
+: returns a 3- or 4-tuple in HSL(a) format. The `alpha` keyword argument can be used to define whether
+  the alpha channel should be included;
+  options: `True` - always include, `False` - never include, `None` (the default)  - include if set
+
+The `__str__` method for `Color` returns `self.as_named(fallback=True)`.
+
+!!! note
+    The `as_hsl*` refer to hue, saturation, lightness "HSL" as used in html and most of the world, **not**
+    "HLS" as used in Python's `colorsys`.

docs/coordinate.md

@@ -0,0 +1,49 @@
+
+Coordinate parses Latitude and Longitude.
+
+You can use the `Coordinate` data type for storing coordinates. Coordinates can be defined using one of the following formats:
+
+1. Tuple format: `(Latitude, Longitude)`. For example: `(41.40338, 2.17403)`.
+2. `Coordinate` instance format: `Coordinate(latitude=Latitude, longitude=Longitude)`. For example: `Coordinate(latitude=41.40338, longitude=2.17403)`.
+
+The `Latitude` class and `Longitude` class, which are used to represent latitude and longitude, respectively, enforce the following valid ranges for their values:
+
+- `Latitude`: The latitude value should be between -90 and 90, inclusive.
+- `Longitude`: The longitude value should be between -180 and 180, inclusive.
+
+```py
+from pydantic import BaseModel
+
+from pydantic_extra_types.coordinate import Longitude, Latitude, Coordinate
+
+
+class Lat(BaseModel):
+    lat: Latitude
+
+
+class Lng(BaseModel):
+    lng: Longitude
+
+
+class Coord(BaseModel):
+    coord: Coordinate
+
+
+lat = Lat(
+    lat='90.0',
+)
+
+lng = Lng(
+    long='180.0'
+)
+
+coord = Coord(
+    coord=('90.0', '180.0')
+)
+print(lat.lat)
+# > 90.0
+print(lng.lng)
+# > 180.0
+print(coord.coord)
+# > 90.0,180.0
+```

docs/extra/terminal.css

@@ -0,0 +1,39 @@
+.terminal {
+  background: #300a24;
+  border-radius: 4px;
+  padding: 5px 10px;
+}
+
+pre.terminal-content {
+  display: inline-block;
+  line-height: 1.3 !important;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+  background: #300a24 !important;
+  color: #d0d0d0 !important;
+}
+
+.ansi2 {
+  font-weight: lighter;
+}
+.ansi3 {
+  font-style: italic;
+}
+.ansi32 {
+  color: #00aa00;
+}
+.ansi34 {
+  color: #5656fe;
+}
+.ansi35 {
+  color: #E850A8;
+}
+.ansi38-1 {
+  color: #cf0000;
+}
+.ansi38-5 {
+  color: #E850A8;
+}
+.ansi38-68 {
+  color: #2a54a8;
+}

docs/extra/tweaks.css

@@ -0,0 +1,77 @@
+.sponsors {
+  display: flex;
+  justify-content: center;
+  flex-wrap: wrap;
+  align-items: center;
+  margin: 1rem 0;
+}
+
+.sponsors > div {
+  text-align: center;
+  width: 33%;
+  padding-bottom: 20px;
+}
+
+.sponsors span {
+  display: block;
+}
+
+@media screen and (max-width: 599px) {
+  .sponsors span {
+    display: none;
+  }
+}
+
+.sponsors img {
+  width: 65%;
+  border-radius: 5px;
+}
+
+/*blog post*/
+aside.blog {
+  display: flex;
+  align-items: center;
+}
+
+aside.blog img {
+  width: 50px;
+  height: 50px;
+  border-radius: 25px;
+  margin-right: 20px;
+}
+
+/* Define the company grid layout */
+
+#grid-container {
+  width: 100%;
+  text-align: center;
+}
+
+#company-grid {
+  display: inline-block;
+  margin: 0 auto;
+  gap: 10px;
+  align-content: center;
+  justify-content: center;
+  grid-auto-flow: column;
+}
+
+[data-md-color-scheme="slate"] #company-grid {
+  background-color: #ffffff;
+  border-radius: .5rem;
+}
+
+.tile {
+  display: flex;
+  text-align: center;
+  width: 120px;
+  height: 120px;
+  display: inline-block;
+  margin: 10px;
+  padding: 5px;
+  border-radius: .5rem;
+}
+
+.tile img {
+  width: 100px;
+}

docs/mac_address.md

@@ -0,0 +1,22 @@
+
+The `MacAddress` type validates [MAC address](https://en.wikipedia.org/wiki/MAC_address) (such as a network card).
+
+```py
+from pydantic import BaseModel
+
+from pydantic_extra_types.mac_address import MacAddress
+
+
+class Network(BaseModel):
+    mac_address: MacAddress
+
+
+network = Network(
+    mac_address='00:00:5e:00:53:01',
+)
+
+print(network.mac_address)
+# > 00:00:5e:00:53:01
+```
+
+The algorithm used to validate the MAC address `IEEE` `802` `MAC-48`, `EUI-48`, `EUI-64`, or a `20-octet`.

docs/payment_cards.md

@@ -0,0 +1,54 @@
+
+The `PaymentCardNumber` type validates [payment cards]
+(such as a debit or credit card).
+
+```py
+from datetime import date
+
+from pydantic import BaseModel, constr
+
+from pydantic_extra_types.payment import PaymentCardBrand, PaymentCardNumber
+
+
+class Card(BaseModel):
+    name: constr(strip_whitespace=True, min_length=1)
+    number: PaymentCardNumber
+    exp: date
+
+    @property
+    def brand(self) -> PaymentCardBrand:
+        return self.number.brand
+
+    @property
+    def expired(self) -> bool:
+        return self.exp < date.today()
+
+
+card = Card(
+    name='Georg Wilhelm Friedrich Hegel',
+    number='4000000000000002',
+    exp=date(2023, 9, 30),
+)
+
+assert card.number.brand == PaymentCardBrand.visa
+assert card.number.bin == '400000'
+assert card.number.last4 == '0002'
+assert card.number.masked == '400000******0002'
+```
+
+`PaymentCardBrand` can be one of the following based on the BIN:
+
+* `PaymentCardBrand.amex`
+* `PaymentCardBrand.mastercard`
+* `PaymentCardBrand.visa`
+* `PaymentCardBrand.other`
+
+The actual validation verifies the card number is:
+
+* a `str` of only digits
+* [luhn](https://en.wikipedia.org/wiki/Luhn_algorithm) valid
+* the correct length based on the BIN, if Amex, Mastercard or Visa, and between
+  12 and 19 digits for all other brands
+
+
+[payment cards]: https://en.wikipedia.org/wiki/Payment_card

docs/phone_numbers.md

@@ -0,0 +1,27 @@
+
+The `PhoneNumber` type validates phone numbers.
+
+This class depends on the [phonenumbers] package, which is a Python port of Google's [libphonenumber].
+
+```py
+from pydantic import BaseModel
+
+from pydantic_extra_types.phone_numbers import PhoneNumber
+
+
+class User(BaseModel):
+    name: str
+    phone_number: PhoneNumber
+
+
+user = User(name='John', phone_number='+447911123456')
+print(user.phone_number)  # (1)!
+#> tel:+44-7911-123456
+```
+
+1. The phone format used is described on the [RFC3966].
+
+
+[phonenumbers]: https://pypi.org/project/phonenumbers/
+[libphonenumber]: https://github.com/google/libphonenumber/
+[RFC3966]: https://tools.ietf.org/html/rfc3966

docs/routing_numbers.md

@@ -0,0 +1,31 @@
+
+The `ABARoutingNumber` type validates [ABA routing transit numbers].
+
+
+```py
+from pydantic import BaseModel
+
+from pydantic_extra_types.routing_number import ABARoutingNumber
+
+
+class BankAccount(BaseModel):
+    name: str
+    routing_number: ABARoutingNumber
+    account_number: str
+
+
+account = BankAccount(
+    name="John",
+    routing_number="122105155",
+    account_number="123456789",
+)
+
+print(account.routing_number)
+# > 122105155
+```
+
+The algorithm used to validate the routing number is described on this [section of the Wikipedia page].
+
+
+[ABA routing transit numbers]: https://en.wikipedia.org/wiki/ABA_routing_transit_number
+[section of the Wikipedia page]: https://en.wikipedia.org/wiki/ABA_routing_transit_number#Check_digit