core.orm.mixins.content
=======================

.. py:module:: core.orm.mixins.content


Attributes
----------

.. autoapisummary::

   core.orm.mixins.content._T
   core.orm.mixins.content._MarkupT
   core.orm.mixins.content.IMMUTABLE_TYPES
   core.orm.mixins.content.content_property
   core.orm.mixins.content.data_property
   core.orm.mixins.content.meta_property
   core.orm.mixins.content.dictionary_based_property_factory


Classes
-------

.. autoapisummary::

   core.orm.mixins.content._dict_property_factory
   core.orm.mixins.content.ContentMixin
   core.orm.mixins.content.dict_property
   core.orm.mixins.content.dict_markup_property


Functions
---------

.. autoapisummary::

   core.orm.mixins.content.is_valid_default
   core.orm.mixins.content.dict_property_factory


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

.. py:class:: _dict_property_factory

   Bases: :py:obj:`Protocol`


   Base class for protocol classes.

   Protocol classes are defined as::

       class Proto(Protocol):
           def meth(self) -> int:
               ...

   Such classes are primarily used with static type checkers that recognize
   structural subtyping (static duck-typing).

   For example::

       class C:
           def meth(self) -> int:
               return 0

       def func(x: Proto) -> int:
           return x.meth()

       func(C())  # Passes static type check

   See PEP 544 for details. Protocol classes decorated with
   @typing.runtime_checkable act as simple-minded runtime protocols that check
   only the presence of given attributes, ignoring their type signatures.
   Protocol classes can be generic, they are defined as::

       class GenProto(Protocol[T]):
           def meth(self) -> T:
               ...


   .. py:method:: __call__(key: str | None = None, default: None = None, value_type: None = None) -> dict_property[Any | None]
                  __call__(key: str | None, default: _T | collections.abc.Callable[[], _T], value_type: None = None) -> dict_property[_T]
                  __call__(key: str | None = None, *, default: _T | collections.abc.Callable[[], _T], value_type: None = None) -> dict_property[_T]
                  __call__(key: str | None, default: None, *, value_type: type[_T]) -> dict_property[_T]
                  __call__(key: str | None = None, default: None = None, *, value_type: type[_T]) -> dict_property[_T]
                  __call__(key: str | None, default: _T | collections.abc.Callable[[], _T], value_type: type[_T]) -> dict_property[_T]
                  __call__(key: str | None = None, *, default: _T | collections.abc.Callable[[], _T], value_type: type[_T]) -> dict_property[_T]


.. py:data:: _T

.. py:data:: _MarkupT

.. py:data:: IMMUTABLE_TYPES

.. py:class:: ContentMixin

   Mixin providing a meta/content JSON pair. Meta is a JSON column loaded
   with each request, content is a JSON column loaded deferred (to be shown
   only in the detail view).



   .. py:property:: meta
      :type: sqlalchemy.schema.Column[dict[str, Any]]



   .. py:property:: content
      :type: sqlalchemy.schema.Column[dict[str, Any]]



.. py:function:: is_valid_default(default: object | None) -> bool

.. py:class:: dict_property(attribute: str, key: str | None = None, default: None = None, value_type: None = None)
              dict_property(attribute: str, key: str | None, default: _T | collections.abc.Callable[[], _T], value_type: None = None)
              dict_property(attribute: str, key: str | None = None, *, default: _T | collections.abc.Callable[[], _T], value_type: None = None)
              dict_property(attribute: str, key: str | None, default: None, *, value_type: type[_T])
              dict_property(attribute: str, key: str | None = None, default: None = None, *, value_type: type[_T])
              dict_property(attribute: str, key: str | None, default: _T | collections.abc.Callable[[], _T], value_type: type[_T])
              dict_property(attribute: str, key: str | None = None, *, default: _T | collections.abc.Callable[[], _T], value_type: type[_T])

   Bases: :py:obj:`sqlalchemy.orm.interfaces.InspectionAttrInfo`, :py:obj:`Generic`\ [\ :py:obj:`_T`\ ]


   Enables access of dictionaries through properties.

   Usage::

       class Model(ContentMixin):
           access_times = dict_property('meta')

   This creates a property that accesses the meta directory with the key
   'access_times'. The key is implicitly copied from the definition.

   Another way of writing this out would be::

       class Model(ContentMixin):
           access_times = dict_property('meta', 'access_times')

   As is apparent, the 'access_times' key is duplicated in this case. Usually
   you do not need to provide the name. The exception being if you want
   the property name and the dictionary key to differ::

       class Model(ContentMixin):
           access_times = dict_property('meta', 'access')

   Here, the key in the dictionary is 'access', while the property is
   'access_times'.

   Since we often use the same kind of dictionaries we can use the builtin
   properties that are scoped to a specific dictionary::

       class Model(ContentMixin):
           access_times = meta_property()

   This is equivalent to the initial example.

   We can also create our own scoped properties as follows:

       foo_property = dict_property_factory('foo')

       class Model:

           foo = {}

           bar = foo_property()

   Here, model.bar would read model.foo['bar'].

   Dict properties are compatible with typical python properties, so the
   usual getter/setter/deleter methods are also available::

       class Model(ContentMixin):
           content = meta_property()

           @content.setter
           def set_content(self, value):
               self.meta['content'] = value
               self.meta['content_html'] = to_html_ul(value)

           @content.deleter
           def del_content(self):
               del self.meta['content']
               del self.meta['content_html']

   This also behaves like a hybrid_property in that you can use
   these properties inside select and filter statements, if you
   provider a custom getter you will also need to provide a custom
   expression, otherwise we will return an expression which retrieves
   the value from the JSON column::

       class Model(ContentMixin):
           names = meta_property(default=list)

       session.query(Model).filter(Model.names.contains('foo'))

   By default that will mean that the RHS of a comparison will also
   expect a JSONB object, but if you explicitly pass in a value_type
   or a default that is not None, then we will try to first convert
   to that type, so type coercion is a bit more flexible::

       class Model(ContentMixin):
           name = meta_property(value_type=str)

       session.query(Model.name)



   .. py:attribute:: is_attribute
      :value: True


      True if this object is a Python :term:`descriptor`.

      This can refer to one of many types.   Usually a
      :class:`.QueryableAttribute` which handles attributes events on behalf
      of a :class:`.MapperProperty`.   But can also be an extension type
      such as :class:`.AssociationProxy` or :class:`.hybrid_property`.
      The :attr:`.InspectionAttr.extension_type` will refer to a constant
      identifying the specific subtype.

      .. seealso::

          :attr:`_orm.Mapper.all_orm_descriptors`




   .. py:attribute:: custom_getter
      :type:  collections.abc.Callable[[Any], _T] | None


   .. py:attribute:: custom_expression
      :type:  collections.abc.Callable[[type[Any]], sqlalchemy.sql.ColumnElement[_T]] | None


   .. py:attribute:: custom_setter
      :type:  collections.abc.Callable[[Any, _T], None] | None


   .. py:attribute:: custom_deleter
      :type:  collections.abc.Callable[[Any], None] | None


   .. py:attribute:: attribute


   .. py:attribute:: key
      :value: None



   .. py:attribute:: default
      :value: None



   .. py:attribute:: value_type
      :value: None



   .. py:attribute:: update_expr
      :value: None



   .. py:method:: __set_name__(owner: type[object], name: str) -> None

      Sets the dictionary key, if none is provided. 



   .. py:property:: getter
      :type: collections.abc.Callable[[collections.abc.Callable[[Any], _T]], Self]



   .. py:property:: setter
      :type: collections.abc.Callable[[collections.abc.Callable[[Any, _T], None]], Self]



   .. py:property:: deleter
      :type: collections.abc.Callable[[collections.abc.Callable[[Any], None]], Self]



   .. py:property:: expression
      :type: collections.abc.Callable[[collections.abc.Callable[[Any], sqlalchemy.sql.ColumnElement[_T]]], Self]



   .. py:method:: _expr(owner: type[Any]) -> sqlalchemy.orm.attributes.QueryableAttribute | None


   .. py:method:: __get__(instance: None, owner: type[object]) -> sqlalchemy.orm.attributes.QueryableAttribute | None
                  __get__(instance: object, owner: type[object]) -> _T


   .. py:method:: __set__(instance: object, value: _T) -> None


   .. py:method:: __delete__(instance: object) -> None


.. py:class:: dict_markup_property(attribute: str, key: str | None = None, default: None = None)
              dict_markup_property(attribute: str, key: str | None, default: markupsafe.Markup)
              dict_markup_property(attribute: str, key: str | None = None, *, default: markupsafe.Markup)

   Bases: :py:obj:`dict_property`\ [\ :py:obj:`_MarkupT`\ ]


   Enables access of dictionaries through properties.

   Usage::

       class Model(ContentMixin):
           access_times = dict_property('meta')

   This creates a property that accesses the meta directory with the key
   'access_times'. The key is implicitly copied from the definition.

   Another way of writing this out would be::

       class Model(ContentMixin):
           access_times = dict_property('meta', 'access_times')

   As is apparent, the 'access_times' key is duplicated in this case. Usually
   you do not need to provide the name. The exception being if you want
   the property name and the dictionary key to differ::

       class Model(ContentMixin):
           access_times = dict_property('meta', 'access')

   Here, the key in the dictionary is 'access', while the property is
   'access_times'.

   Since we often use the same kind of dictionaries we can use the builtin
   properties that are scoped to a specific dictionary::

       class Model(ContentMixin):
           access_times = meta_property()

   This is equivalent to the initial example.

   We can also create our own scoped properties as follows:

       foo_property = dict_property_factory('foo')

       class Model:

           foo = {}

           bar = foo_property()

   Here, model.bar would read model.foo['bar'].

   Dict properties are compatible with typical python properties, so the
   usual getter/setter/deleter methods are also available::

       class Model(ContentMixin):
           content = meta_property()

           @content.setter
           def set_content(self, value):
               self.meta['content'] = value
               self.meta['content_html'] = to_html_ul(value)

           @content.deleter
           def del_content(self):
               del self.meta['content']
               del self.meta['content_html']

   This also behaves like a hybrid_property in that you can use
   these properties inside select and filter statements, if you
   provider a custom getter you will also need to provide a custom
   expression, otherwise we will return an expression which retrieves
   the value from the JSON column::

       class Model(ContentMixin):
           names = meta_property(default=list)

       session.query(Model).filter(Model.names.contains('foo'))

   By default that will mean that the RHS of a comparison will also
   expect a JSONB object, but if you explicitly pass in a value_type
   or a default that is not None, then we will try to first convert
   to that type, so type coercion is a bit more flexible::

       class Model(ContentMixin):
           name = meta_property(value_type=str)

       session.query(Model.name)



   .. py:attribute:: custom_expression


   .. py:method:: __get__(instance: None, owner: type[object]) -> sqlalchemy.orm.attributes.QueryableAttribute | None
                  __get__(instance: object, owner: type[object]) -> _MarkupT


   .. py:method:: __set__(instance: object, value: _MarkupT) -> None


.. py:function:: dict_property_factory(attribute: str) -> _dict_property_factory

.. py:data:: content_property

.. py:data:: data_property

.. py:data:: meta_property

.. py:data:: dictionary_based_property_factory