sanmar_sdk.base
===============

.. py:module:: sanmar_sdk.base

.. autoapi-nested-parse::

   Base classes and field types shared by every model in the SDK.

   There are two kinds of model:

   - :class:`Model` is anything a caller builds and hands to the SDK: a purchase order, a
     lookup. It is strict — a string is not coerced into a number, a float is not accepted as
     money — so a mistake fails when the model is built, before anything is sent to SanMar.
   - :class:`Record` is anything the SDK parses out of a SanMar response or data file. SanMar
     types almost everything as text, so records coerce leniently, ignore fields they do not
     model, and treat a missing or blank value as absent.



Attributes
----------

.. autoapisummary::

   sanmar_sdk.base.SanMarDate
   sanmar_sdk.base.OneOrMany
   sanmar_sdk.base.Price
   sanmar_sdk.base.CommaSeparated
   sanmar_sdk.base.SemicolonSeparated
   sanmar_sdk.base.ORDER_TEXT
   sanmar_sdk.base.FROZEN


Classes
-------

.. autoapisummary::

   sanmar_sdk.base.Model
   sanmar_sdk.base.Record


Module Contents
---------------

.. py:class:: Model(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   A strict, immutable model that a caller builds.


   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


.. py:class:: Record(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   An immutable model parsed from something SanMar sent.


   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


.. py:data:: SanMarDate

   A date in any of the formats SanMar sends.

.. py:type:: OneOrMany
   :canonical: Annotated[list[T], BeforeValidator(_as_list)]


   A list that SanMar may send as a single item when there is only one.

.. py:data:: Price

   A dollar amount, or ``None`` where SanMar has none (a blank, ``NA`` or ``NLA``).

.. py:data:: CommaSeparated

   A comma-separated list, split into its parts.

.. py:data:: SemicolonSeparated

   A semicolon-separated list, split into its parts.

.. py:data:: ORDER_TEXT

   Marks a string as text that goes into a SanMar order, which takes printable ASCII without commas.

   It goes after the field's length limits, so a too-long value is reported in characters::

       city: Annotated[str, Field(max_length=28), ORDER_TEXT]

.. py:data:: FROZEN

   Stores a validated collection as a tuple, so a frozen model's collection cannot change.

   Callers may pass any sequence, a list included; without this, a list would be kept as the
   same mutable list, and emptying it would get past the model's validation::

       lines: Annotated[Sequence[OrderLine], Field(min_length=1), FROZEN]