Skip to content

omnipy.components.remote.models

Models for HTTP URLs, URL parts, query strings, and automatic response decoding.

CLASS DESCRIPTION
HttpUrlModel

Represent a validated HTTP or HTTPS URL as a structured model.
QueryParamsModel

Represent URL query parameters as a decoded key-value mapping.
UrlDataclassModel

Store mutable URL components used by :class:HttpUrlModel.
UrlPathModel

Represent a URL path with path-like joining and mutation helpers.

DEFAULT_PORTS module-attribute 

DEFAULT_PORTS = {80, 443}

QueryParamsJoinerModel module-attribute 

QueryParamsJoinerModel = NestedJoinItemsModel.adjust(
    "QueryParamsJoinerModel", delimiters=("&", "=")
)

QueryParamsSplitterModel module-attribute 

QueryParamsSplitterModel = NestedSplitToItemsModel.adjust(
    "QueryParamsSplitterModel", delimiters=("&", "=")
)

AutoResponseContentModel

Bases: Model[ResponseContentPydModel | StrictBytesModel | StrictStrModel | JsonListOrDictModel]


              flowchart BT
              omnipy.components.remote.models.AutoResponseContentModel[AutoResponseContentModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]

                              omnipy.data.model.Model --> omnipy.components.remote.models.AutoResponseContentModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                



              click omnipy.components.remote.models.AutoResponseContentModel href "" "omnipy.components.remote.models.AutoResponseContentModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"

Decode HTTP response content to bytes, text, or JSON from MIME metadata.

PARAMETER DESCRIPTION
*args

Positional data forwarded to :class:~omnipy.data.model.Model.
**kwargs

Keyword arguments forwarded to :class:~omnipy.data.model.Model.

TYPE: _RootT | object DEFAULT: {}

RETURNS DESCRIPTION
AutoResponseContentModel

Model containing auto-decoded response content.
RAISES DESCRIPTION
AssertionError

If wrapped response metadata is missing parsed MIME type data.
Returned by: Subclassed by:
CLASS DESCRIPTION
Config

Configure union parsing for automatic response-content decoding.
Source code in src/omnipy/components/remote/models.py 
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
class AutoResponseContentModel(Model[ResponseContentPydModel | StrictBytesModel | StrictStrModel
                                     | JsonListOrDictModel]):
    """Decode HTTP response content to bytes, text, or JSON from MIME metadata.

    Args:
        *args: Positional data forwarded to :class:`~omnipy.data.model.Model`.
        **kwargs: Keyword arguments forwarded to
            :class:`~omnipy.data.model.Model`.

    Returns:
        AutoResponseContentModel: Model containing auto-decoded response content.

    Raises:
        AssertionError: If wrapped response metadata is missing parsed MIME type data.
    """
    class Config(Model.Config):
        """Configure union parsing for automatic response-content decoding.

        Smart-union matching is disabled so MIME-driven model selection for
        bytes, text, and JSON remains explicit.
        """

        smart_union = False

    @classmethod
    def _parse_data(  # type: ignore[override]
        cls,
        data: ResponseContentPydModel | StrictBytesModel | StrictStrModel | AnyJsonListOrDictModel
    ) -> StrictBytesModel | StrictStrModel | AnyJsonListOrDictModel:
        """Choose response model type from MIME type and payload.

        Args:
            data: Wrapped response metadata or pre-decoded response model.

        Returns:
            StrictBytesModel | StrictStrModel | AnyJsonListOrDictModel: Response model selected
            from MIME metadata.

        Raises:
            AssertionError: If wrapped input is missing parsed MIME type data.
        """
        if isinstance(data, ResponseContentPydModel):
            assert isinstance(data.content_type, ModelFriendlyMimeType)

            mimetype_tuple = (data.content_type.type, data.content_type.subtype)
            match mimetype_tuple:
                case ('application', 'json'):
                    return JsonListOrDictModel(data.response)
                case ('text', 'plain'):
                    return StrictStrModel(data.response)
                case ('application', 'octet-stream') | _:
                    return StrictBytesModel(data.response)
        else:
            return data

Config

Bases: Model.Config


              flowchart BT
              omnipy.components.remote.models.AutoResponseContentModel.Config[Config]
              omnipy.data.model.Model.Config[Config]

                              omnipy.data.model.Model.Config --> omnipy.components.remote.models.AutoResponseContentModel.Config
                


              click omnipy.components.remote.models.AutoResponseContentModel.Config href "" "omnipy.components.remote.models.AutoResponseContentModel.Config"
              click omnipy.data.model.Model.Config href "" "omnipy.data.model.Model.Config"

Configure union parsing for automatic response-content decoding.

Smart-union matching is disabled so MIME-driven model selection for bytes, text, and JSON remains explicit.

ATTRIBUTE DESCRIPTION
smart_union

Source code in src/omnipy/components/remote/models.py 
466
467
468
469
470
471
472
473
class Config(Model.Config):
    """Configure union parsing for automatic response-content decoding.

    Smart-union matching is disabled so MIME-driven model selection for
    bytes, text, and JSON remains explicit.
    """

    smart_union = False

smart_union class-attribute instance-attribute 

smart_union = False

HttpUrlModel

Bases: Model[UrlDataclassModel | str]


              flowchart BT
              omnipy.components.remote.models.HttpUrlModel[HttpUrlModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]

                              omnipy.data.model.Model --> omnipy.components.remote.models.HttpUrlModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                



              click omnipy.components.remote.models.HttpUrlModel href "" "omnipy.components.remote.models.HttpUrlModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"

Represent a validated HTTP or HTTPS URL as a structured model.

PARAMETER DESCRIPTION
*args

Positional data forwarded to :class:~omnipy.data.model.Model.
**kwargs

Keyword arguments forwarded to :class:~omnipy.data.model.Model.

TYPE: _RootT | object DEFAULT: {}

RETURNS DESCRIPTION
HttpUrlModel

Model instance containing validated URL components.
RAISES DESCRIPTION
AssertionError

If the URL scheme is not http or https.
pyd.ValidationError

If URL parsing fails.
Example

url = HttpUrlModel('https://example.com/path?q=1') str(url) 'https://example.com/path?q=1'

Subclassed by: Used by:
METHOD DESCRIPTION
to_data

Return the normalized URL as a string.
Source code in src/omnipy/components/remote/models.py 
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
class HttpUrlModel(Model[UrlDataclassModel | str]):
    """Represent a validated HTTP or HTTPS URL as a structured model.

    Args:
        *args: Positional data forwarded to :class:`~omnipy.data.model.Model`.
        **kwargs: Keyword arguments forwarded to
            :class:`~omnipy.data.model.Model`.

    Returns:
        HttpUrlModel: Model instance containing validated URL components.

    Raises:
        AssertionError: If the URL scheme is not ``http`` or ``https``.
        pyd.ValidationError: If URL parsing fails.

    Example:
        >>> url = HttpUrlModel('https://example.com/path?q=1')
        >>> str(url)
        'https://example.com/path?q=1'
    """

    if TYPE_CHECKING:

        def __new__(cls, *args: Any, **kwargs: Any) -> 'HttpUrlModel_UrlDataclassModel':
            ...

    @classmethod
    def _parse_data(cls, data: UrlDataclassModel | str) -> UrlDataclassModel:
        """Parse and validate URL data into :class:`UrlDataclassModel`.

        Args:
            data: URL string or prebuilt URL dataclass model.

        Returns:
            UrlDataclassModel: Parsed URL parts with normalized decoded fields.

    Raises:
        AssertionError: If the URL scheme is unsupported.
        pyd.ValidationError: If the URL cannot be parsed.
        """
        if data == '':
            data = 'http://localhost/'
        if data == 'https://':
            data = 'https://localhost/'
        # For validation only
        url_obj = pyd.Url(str(data) if isinstance(data, UrlDataclassModel) else data)

        parts: dict[str, str | int | None] = {}
        for key in UrlDataclassModel.__fields__.keys():
            match key:
                case 'scheme':
                    val = url_obj.scheme
                    assert val in {'http', 'https'}, f'Unsupported scheme: {val}'
                    parts[key] = val
                case 'host':
                    parts[key] = url_obj.unicode_host()
                case 'username' | 'password' | 'path' | 'fragment':
                    val = getattr(url_obj, key)
                    parts[key] = unquote(val) if val is not None else None
                case _:
                    parts[key] = getattr(url_obj, key)

        return UrlDataclassModel(**{
            key: val  # type: ignore[arg-type]
            for key, val in parts.items()
            if val is not None
        })

    def __add__(self, other: str) -> 'HttpUrlModel':
        return HttpUrlModel(str(self) + other)

    def to_data(self) -> str:
        """Return the normalized URL as a string.

        Returns:
            str: Fully rendered HTTP(S) URL string.
        """

        return str(self.content)

    def __str__(self) -> str:
        return str(self.content)

to_data 

to_data() -> str

Return the normalized URL as a string.

RETURNS DESCRIPTION
str

Fully rendered HTTP(S) URL string.

TYPE: str

Source code in src/omnipy/components/remote/models.py 
353
354
355
356
357
358
359
360
def to_data(self) -> str:
    """Return the normalized URL as a string.

    Returns:
        str: Fully rendered HTTP(S) URL string.
    """

    return str(self.content)

HttpUrlModel_UrlDataclassModel

Bases: HttpUrlModel, UrlDataclassModel


              flowchart BT
              omnipy.components.remote.models.HttpUrlModel_UrlDataclassModel[HttpUrlModel_UrlDataclassModel]
              omnipy.components.remote.models.HttpUrlModel[HttpUrlModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]
              omnipy.components.remote.models.UrlDataclassModel[UrlDataclassModel]

                              omnipy.components.remote.models.HttpUrlModel --> omnipy.components.remote.models.HttpUrlModel_UrlDataclassModel
                                omnipy.data.model.Model --> omnipy.components.remote.models.HttpUrlModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                


                omnipy.components.remote.models.UrlDataclassModel --> omnipy.components.remote.models.HttpUrlModel_UrlDataclassModel
                                omnipy.util.pydantic.BaseModel --> omnipy.components.remote.models.UrlDataclassModel
                



              click omnipy.components.remote.models.HttpUrlModel_UrlDataclassModel href "" "omnipy.components.remote.models.HttpUrlModel_UrlDataclassModel"
              click omnipy.components.remote.models.HttpUrlModel href "" "omnipy.components.remote.models.HttpUrlModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"
              click omnipy.components.remote.models.UrlDataclassModel href "" "omnipy.components.remote.models.UrlDataclassModel"

Type-checking helper combining URL model and URL-part attributes.

This helper exists only for static typing so parsed URL fields can be accessed directly on HttpUrlModel values.

Source code in src/omnipy/components/remote/models.py 
368
369
370
371
372
373
374
375
class HttpUrlModel_UrlDataclassModel(HttpUrlModel, UrlDataclassModel):  # type: ignore[misc]
    """Type-checking helper combining URL model and URL-part attributes.

    This helper exists only for static typing so parsed URL fields can be
    accessed directly on ``HttpUrlModel`` values.
    """

    ...

ModelFriendlyMimeType

Bases: pyd.BaseModel


              flowchart BT
              omnipy.components.remote.models.ModelFriendlyMimeType[ModelFriendlyMimeType]

                              omnipy.util.pydantic.BaseModel --> omnipy.components.remote.models.ModelFriendlyMimeType
                


              click omnipy.components.remote.models.ModelFriendlyMimeType href "" "omnipy.components.remote.models.ModelFriendlyMimeType"

Store MIME type parts in a model-friendly immutable representation.

PARAMETER DESCRIPTION
type

MIME top-level type such as application or text.
subtype

MIME subtype such as json or plain.
suffix

Optional structured syntax suffix.
parameters

MIME parameters as key-value pairs.
RETURNS DESCRIPTION
ModelFriendlyMimeType

MIME parts represented as simple model fields.
RAISES DESCRIPTION
pyd.ValidationError

If supplied fields do not match expected types.
Returned by: Used by:
ATTRIBUTE DESCRIPTION
parameters

TYPE: tuple[tuple[str, str], ...]

subtype

TYPE: str

suffix

TYPE: str

type

TYPE: str

Source code in src/omnipy/components/remote/models.py 
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
class ModelFriendlyMimeType(pyd.BaseModel):
    """Store MIME type parts in a model-friendly immutable representation.

    Args:
        type: MIME top-level type such as ``application`` or ``text``.
        subtype: MIME subtype such as ``json`` or ``plain``.
        suffix: Optional structured syntax suffix.
        parameters: MIME parameters as key-value pairs.

    Returns:
        ModelFriendlyMimeType: MIME parts represented as simple model fields.

    Raises:
        pyd.ValidationError: If supplied fields do not match expected types.
    """
    type: str
    subtype: str
    suffix: str
    parameters: tuple[tuple[str, str], ...]

parameters instance-attribute 

parameters: tuple[tuple[str, str], ...]

subtype instance-attribute 

subtype: str

suffix instance-attribute 

suffix: str

type instance-attribute 

type: str

QueryParamsModel

Bases: Model[dict[str, str] | tuple[tuple[str, str], ...] | tuple[str, ...] | str]


              flowchart BT
              omnipy.components.remote.models.QueryParamsModel[QueryParamsModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]

                              omnipy.data.model.Model --> omnipy.components.remote.models.QueryParamsModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                



              click omnipy.components.remote.models.QueryParamsModel href "" "omnipy.components.remote.models.QueryParamsModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"

Represent URL query parameters as a decoded key-value mapping.

PARAMETER DESCRIPTION
*args

Positional data forwarded to :class:~omnipy.data.model.Model.
**kwargs

Keyword arguments forwarded to :class:~omnipy.data.model.Model.

TYPE: _RootT | object DEFAULT: {}

RETURNS DESCRIPTION
QueryParamsModel

Model instance containing decoded query parameters.
RAISES DESCRIPTION
AssertionError

If tuple-like input does not contain key-value pairs.
Example

params = QueryParamsModel('name=alice&lang=en') str(params) 'name=alice&lang=en'

Subclassed by: Used by:
METHOD DESCRIPTION
to_data

Serialize query parameters back to a URL-encoded query string.
Source code in src/omnipy/components/remote/models.py 
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
class QueryParamsModel(Model[dict[str, str] | tuple[tuple[str, str], ...] | tuple[str, ...] | str]):
    """Represent URL query parameters as a decoded key-value mapping.

    Args:
        *args: Positional data forwarded to :class:`~omnipy.data.model.Model`.
        **kwargs: Keyword arguments forwarded to
            :class:`~omnipy.data.model.Model`.

    Returns:
        QueryParamsModel: Model instance containing decoded query parameters.

    Raises:
        AssertionError: If tuple-like input does not contain key-value pairs.

    Example:
        >>> params = QueryParamsModel('name=alice&lang=en')
        >>> str(params)
        'name=alice&lang=en'
    """

    if TYPE_CHECKING and TYPE_CHECKER != 'mypy':

        def __new__(cls, *args: Any, **kwargs: Any) -> 'QueryParamsModel_dict':
            ...

    @classmethod
    def _validate_tuple_of_pairs(
            cls, params_list: list[str | list] | str) -> TypeGuard[list[tuple[str, str]]]:
        """Check that each split query parameter contains exactly two elements.

        Args:
            params_list: Split query representation produced by
                ``QueryParamsSplitterModel``.

        Returns:
            bool: ``True`` when every element is a two-item list ``[key, value]``.
        """
        # The validated type is really a list of lists of two items, but we can't express that with
        # Python type hints, so we use a list of tuple pairs instead.
        return all(isinstance(param, list) and len(param) == 2 for param in params_list)

    @classmethod
    def _parse_data(
        cls, data: dict[str, str] | tuple[tuple[str, str], ...] | tuple[str, ...] | str
    ) -> dict[str, str]:
        """Parse supported query-parameter inputs into a decoded mapping.

        Args:
            data: Query parameters as a mapping, tuple pairs, or URL query string.

        Returns:
            dict[str, str]: Decoded query parameters.

    Raises:
        AssertionError: If non-mapping input does not split into key-value pairs.
        """
        if isinstance(data, dict):
            return data

        params_list = QueryParamsSplitterModel(data).content
        assert cls._validate_tuple_of_pairs(params_list), \
            (f'Each parameter must have 2 elements only: [key, value]. '
             f'Incorrect parameter list: {params_list}')

        return dict((unquote(key), unquote(val)) for key, val in params_list)

    def to_data(self) -> str:
        """Serialize query parameters back to a URL-encoded query string.

        Returns:
            str: URL-encoded query string without a leading ``?``.

        Raises:
            AssertionError: If model content is not a dictionary at serialization time.
        """
        with hold_and_reset_prev_attrib_value(self.config.model,
                                              'dynamically_convert_elements_to_models'):
            self.config.model.dynamically_convert_elements_to_models = False
            assert isinstance(self.content, dict)
            url_encoded_content = tuple(
                (quote(key), quote(val)) for key, val in self.content.items())
            return cast(str, QueryParamsJoinerModel(url_encoded_content).to_data())

    def __str__(self) -> str:
        return self.to_data()

to_data 

to_data() -> str

Serialize query parameters back to a URL-encoded query string.

RETURNS DESCRIPTION
str

URL-encoded query string without a leading ?.

TYPE: str

RAISES DESCRIPTION
AssertionError

If model content is not a dictionary at serialization time.
Source code in src/omnipy/components/remote/models.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def to_data(self) -> str:
    """Serialize query parameters back to a URL-encoded query string.

    Returns:
        str: URL-encoded query string without a leading ``?``.

    Raises:
        AssertionError: If model content is not a dictionary at serialization time.
    """
    with hold_and_reset_prev_attrib_value(self.config.model,
                                          'dynamically_convert_elements_to_models'):
        self.config.model.dynamically_convert_elements_to_models = False
        assert isinstance(self.content, dict)
        url_encoded_content = tuple(
            (quote(key), quote(val)) for key, val in self.content.items())
        return cast(str, QueryParamsJoinerModel(url_encoded_content).to_data())

QueryParamsModel_dict

Bases: QueryParamsModel, dict


              flowchart BT
              omnipy.components.remote.models.QueryParamsModel_dict[QueryParamsModel_dict]
              omnipy.components.remote.models.QueryParamsModel[QueryParamsModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]

                              omnipy.components.remote.models.QueryParamsModel --> omnipy.components.remote.models.QueryParamsModel_dict
                                omnipy.data.model.Model --> omnipy.components.remote.models.QueryParamsModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                




              click omnipy.components.remote.models.QueryParamsModel_dict href "" "omnipy.components.remote.models.QueryParamsModel_dict"
              click omnipy.components.remote.models.QueryParamsModel href "" "omnipy.components.remote.models.QueryParamsModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"

Type-checking helper refining QueryParamsModel as dict-like.

This helper exists only for static typing so query-parameter model instances can be treated as decoded string-to-string mappings.

Returned by:
Source code in src/omnipy/components/remote/models.py 
121
122
123
124
125
126
127
128
class QueryParamsModel_dict(QueryParamsModel, dict):  # type: ignore[misc]
    """Type-checking helper refining ``QueryParamsModel`` as ``dict``-like.

    This helper exists only for static typing so query-parameter model
    instances can be treated as decoded string-to-string mappings.
    """

    ...

ResponseContentPydModel

Bases: pyd.BaseModel


              flowchart BT
              omnipy.components.remote.models.ResponseContentPydModel[ResponseContentPydModel]

                              omnipy.util.pydantic.BaseModel --> omnipy.components.remote.models.ResponseContentPydModel
                


              click omnipy.components.remote.models.ResponseContentPydModel href "" "omnipy.components.remote.models.ResponseContentPydModel"

Pair response payload data with the content type used for decoding.

PARAMETER DESCRIPTION
content_type

MIME type string or pre-parsed ModelFriendlyMimeType.
response

Raw decoded payload from HTTP response handling.
RETURNS DESCRIPTION
ResponseContentPydModel

Validated wrapper for content type and payload.
RAISES DESCRIPTION
pyd.ValidationError

If the MIME type cannot be parsed.
Subclassed by:
CLASS DESCRIPTION
Config

Configure pydantic behavior for response-wrapper validation.
METHOD DESCRIPTION
parse_content_type

Parse MIME content type strings into ModelFriendlyMimeType.
ATTRIBUTE DESCRIPTION
content_type

TYPE: ModelFriendlyMimeType | str

response

TYPE: object

Source code in src/omnipy/components/remote/models.py 
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
class ResponseContentPydModel(pyd.BaseModel):
    """Pair response payload data with the content type used for decoding.

    Args:
        content_type: MIME type string or pre-parsed ``ModelFriendlyMimeType``.
        response: Raw decoded payload from HTTP response handling.

    Returns:
        ResponseContentPydModel: Validated wrapper for content type and payload.

    Raises:
        pyd.ValidationError: If the MIME type cannot be parsed.
    """
    content_type: ModelFriendlyMimeType | str
    response: object

    class Config:
        """Configure pydantic behavior for response-wrapper validation.

        Arbitrary payload object types are allowed so decoded response content
        can be preserved without additional wrapping.
        """

        arbitrary_types_allowed = True

    @pyd.validator('content_type', allow_reuse=True)
    def parse_content_type(cls, content_type: ModelFriendlyMimeType | str) -> ModelFriendlyMimeType:
        """Parse MIME content type strings into ``ModelFriendlyMimeType``.

        Args:
            content_type: MIME type value to normalize.

        Returns:
            ModelFriendlyMimeType: Parsed MIME type model.

    Raises:
        ValueError: If MIME parsing fails for a string input.
        """
        from .lazy_import import MimeType, parse_mimetype

        if isinstance(content_type, ModelFriendlyMimeType):
            return content_type

        mime_type: MimeType = parse_mimetype(content_type)
        return ModelFriendlyMimeType(
            type=mime_type.type,
            subtype=mime_type.subtype,
            suffix=mime_type.suffix,
            parameters=tuple(mime_type.parameters.items()),
        )

content_type instance-attribute 

content_type: ModelFriendlyMimeType | str

response instance-attribute 

response: object

Config

Configure pydantic behavior for response-wrapper validation.

Arbitrary payload object types are allowed so decoded response content can be preserved without additional wrapping.

ATTRIBUTE DESCRIPTION
arbitrary_types_allowed

Source code in src/omnipy/components/remote/models.py 
415
416
417
418
419
420
421
422
class Config:
    """Configure pydantic behavior for response-wrapper validation.

    Arbitrary payload object types are allowed so decoded response content
    can be preserved without additional wrapping.
    """

    arbitrary_types_allowed = True

arbitrary_types_allowed class-attribute instance-attribute 

arbitrary_types_allowed = True

parse_content_type 

parse_content_type(content_type: ModelFriendlyMimeType | str) -> ModelFriendlyMimeType

Parse MIME content type strings into ModelFriendlyMimeType.

Args:
    content_type: MIME type value to normalize.

Returns:
    ModelFriendlyMimeType: Parsed MIME type model.
RAISES DESCRIPTION
ValueError

If MIME parsing fails for a string input.
Source code in src/omnipy/components/remote/models.py 
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
@pyd.validator('content_type', allow_reuse=True)
def parse_content_type(cls, content_type: ModelFriendlyMimeType | str) -> ModelFriendlyMimeType:
    """Parse MIME content type strings into ``ModelFriendlyMimeType``.

    Args:
        content_type: MIME type value to normalize.

    Returns:
        ModelFriendlyMimeType: Parsed MIME type model.

Raises:
    ValueError: If MIME parsing fails for a string input.
    """
    from .lazy_import import MimeType, parse_mimetype

    if isinstance(content_type, ModelFriendlyMimeType):
        return content_type

    mime_type: MimeType = parse_mimetype(content_type)
    return ModelFriendlyMimeType(
        type=mime_type.type,
        subtype=mime_type.subtype,
        suffix=mime_type.suffix,
        parameters=tuple(mime_type.parameters.items()),
    )

UrlDataclassModel

Bases: pyd.BaseModel


              flowchart BT
              omnipy.components.remote.models.UrlDataclassModel[UrlDataclassModel]

                              omnipy.util.pydantic.BaseModel --> omnipy.components.remote.models.UrlDataclassModel
                


              click omnipy.components.remote.models.UrlDataclassModel href "" "omnipy.components.remote.models.UrlDataclassModel"

Store mutable URL components used by :class:HttpUrlModel.

PARAMETER DESCRIPTION
scheme

URL scheme, currently expected to be http or https.
username

Optional username part of the URL authority.
password

Optional password part of the URL authority.
host

Hostname or IP address.
port

Optional explicit port number.
path

URL path represented as :class:UrlPathModel.
query

Query parameters represented as :class:QueryParamsModel.
fragment

Optional URL fragment value.
RETURNS DESCRIPTION
UrlDataclassModel

Structured URL parts that can be rendered as a URL string.
RAISES DESCRIPTION
pyd.ValidationError

If any URL part violates model field constraints.
Example

parts = UrlDataclassModel(scheme='https', host='example.com') str(parts) 'https://example.com/'

Subclassed by:
ATTRIBUTE DESCRIPTION
fragment

TYPE: str | None

host

TYPE: str

password

TYPE: str | None

path

TYPE: UrlPathModel_PurePosixPath

port

TYPE: int | None

query

TYPE: QueryParamsModel_dict

scheme

TYPE: str

username

TYPE: str | None

Source code in src/omnipy/components/remote/models.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
class UrlDataclassModel(pyd.BaseModel):
    """Store mutable URL components used by :class:`HttpUrlModel`.

    Args:
        scheme: URL scheme, currently expected to be ``http`` or ``https``.
        username: Optional username part of the URL authority.
        password: Optional password part of the URL authority.
        host: Hostname or IP address.
        port: Optional explicit port number.
        path: URL path represented as :class:`UrlPathModel`.
        query: Query parameters represented as :class:`QueryParamsModel`.
        fragment: Optional URL fragment value.

    Returns:
        UrlDataclassModel: Structured URL parts that can be rendered as a URL string.

    Raises:
        pyd.ValidationError: If any URL part violates model field constraints.

    Example:
        >>> parts = UrlDataclassModel(scheme='https', host='example.com')
        >>> str(parts)
        'https://example.com/'
    """
    # Mutable fields
    scheme: str
    username: str | None = None
    password: str | None = None
    host: str = 'localhost'
    port: int | None = None

    if TYPE_CHECKING:
        path: UrlPathModel_PurePosixPath = pyd.Field(default_factory=UrlPathModel)
        query: QueryParamsModel_dict = pyd.Field(default_factory=QueryParamsModel)

    else:
        path: UrlPathModel = pyd.Field(default_factory=UrlPathModel)
        query: QueryParamsModel = pyd.Field(default_factory=QueryParamsModel)

    fragment: str | None = None

    def __str__(self) -> str:
        kwargs: dict[str, str | int] = {}
        for key, val in self.dict().items():
            if val is None:
                continue
            match key:
                case 'port':
                    if val in DEFAULT_PORTS:
                        continue
                    kwargs[key] = val
                case 'path':
                    # Fix for second problem described in
                    # https://github.com/pydantic/pydantic/issues/7186#issuecomment-1912791497
                    if val != '.':
                        kwargs[key] = val.lstrip('/')
                case 'query':
                    if val:
                        kwargs[key] = str(val)
                case _:
                    kwargs[key] = val

        return str(pyd.Url.build(**kwargs))  # type: ignore[arg-type]

fragment class-attribute instance-attribute 

fragment: str | None = None

host class-attribute instance-attribute 

host: str = 'localhost'

password class-attribute instance-attribute 

password: str | None = None

path class-attribute instance-attribute 

path: UrlPathModel_PurePosixPath = pyd.Field(default_factory=UrlPathModel)

port class-attribute instance-attribute 

port: int | None = None

query class-attribute instance-attribute 

query: QueryParamsModel_dict = pyd.Field(default_factory=QueryParamsModel)

scheme instance-attribute 

scheme: str

username class-attribute instance-attribute 

username: str | None = None

UrlPathModel

Bases: Model[PurePosixPath | str]


              flowchart BT
              omnipy.components.remote.models.UrlPathModel[UrlPathModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]

                              omnipy.data.model.Model --> omnipy.components.remote.models.UrlPathModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                



              click omnipy.components.remote.models.UrlPathModel href "" "omnipy.components.remote.models.UrlPathModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"

Represent a URL path with path-like joining and mutation helpers.

PARAMETER DESCRIPTION
*args

Positional data forwarded to :class:~omnipy.data.model.Model.
**kwargs

Keyword arguments forwarded to :class:~omnipy.data.model.Model.

TYPE: _RootT | object DEFAULT: {}

RETURNS DESCRIPTION
UrlPathModel

Model instance wrapping a PurePosixPath.
RAISES DESCRIPTION
TypeError

If input cannot be converted to PurePosixPath.
Example

path = UrlPathModel('/api') str(path / 'users') '/api/users'

Subclassed by: Used by:
METHOD DESCRIPTION
to_data

Return the normalized URL path as a string.
Source code in src/omnipy/components/remote/models.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
class UrlPathModel(Model[PurePosixPath | str]):
    """Represent a URL path with path-like joining and mutation helpers.

    Args:
        *args: Positional data forwarded to :class:`~omnipy.data.model.Model`.
        **kwargs: Keyword arguments forwarded to
            :class:`~omnipy.data.model.Model`.

    Returns:
        UrlPathModel: Model instance wrapping a ``PurePosixPath``.

    Raises:
        TypeError: If input cannot be converted to ``PurePosixPath``.

    Example:
        >>> path = UrlPathModel('/api')
        >>> str(path / 'users')
        '/api/users'
    """

    if TYPE_CHECKING and TYPE_CHECKER != 'mypy':

        def __new__(cls, *args: Any, **kwargs: Any) -> 'UrlPathModel_PurePosixPath':
            ...

    @classmethod
    def _parse_data(cls, data: PurePosixPath | str) -> PurePosixPath:
        """Normalize path input to a ``PurePosixPath`` instance.

        Args:
            data: URL path provided as a string or path object.

        Returns:
            PurePosixPath: Normalized path value.

    Raises:
        TypeError: If ``data`` is neither ``str`` nor ``PurePosixPath``.
        """
        return PurePosixPath(data) if isinstance(data, str) else data

    def to_data(self) -> str:
        """Return the normalized URL path as a string.

        Returns:
            str: Path content rendered as a POSIX-style string.
        """

        return str(self.content)

    def __str__(self) -> str:
        return str(self.content)

    def _slash_operator(self, other: PurePosixPath | str | object) -> PurePosixPath:
        content = cast(PurePosixPath, self.content)
        match other:
            case PurePosixPath() | str():
                return content / other
            case _:
                return content / str(other)

    def __truediv__(self, other: PurePosixPath | str | object) -> 'UrlPathModel_PurePosixPath':
        return UrlPathModel(self._slash_operator(other))

    def __floordiv__(self, other: PurePosixPath | str | object) -> 'UrlPathModel_PurePosixPath':
        self.content = self._slash_operator(other)
        return self  # type: ignore[return-value]

    def __add__(self, other: PurePosixPath | str | object) -> 'UrlPathModel_PurePosixPath':
        return UrlPathModel(str(self) + str(other))

to_data 

to_data() -> str

Return the normalized URL path as a string.

RETURNS DESCRIPTION
str

Path content rendered as a POSIX-style string.

TYPE: str

Source code in src/omnipy/components/remote/models.py 
171
172
173
174
175
176
177
178
def to_data(self) -> str:
    """Return the normalized URL path as a string.

    Returns:
        str: Path content rendered as a POSIX-style string.
    """

    return str(self.content)

UrlPathModel_PurePosixPath

Bases: UrlPathModel, PurePosixPath


              flowchart BT
              omnipy.components.remote.models.UrlPathModel_PurePosixPath[UrlPathModel_PurePosixPath]
              omnipy.components.remote.models.UrlPathModel[UrlPathModel]
              omnipy.data.model.Model[Model]
              omnipy.data._mixins.display.ModelDisplayMixin[ModelDisplayMixin]
              omnipy.data._mixins.display.BaseDisplayMixin[BaseDisplayMixin]
              omnipy.data._data_class_creator.DataClassBase[DataClassBase]

                              omnipy.components.remote.models.UrlPathModel --> omnipy.components.remote.models.UrlPathModel_PurePosixPath
                                omnipy.data.model.Model --> omnipy.components.remote.models.UrlPathModel
                                omnipy.data._mixins.display.ModelDisplayMixin --> omnipy.data.model.Model
                                omnipy.data._mixins.display.BaseDisplayMixin --> omnipy.data._mixins.display.ModelDisplayMixin
                

                omnipy.data._data_class_creator.DataClassBase --> omnipy.data.model.Model
                
                omnipy.util.pydantic.GenericModel --> omnipy.data.model.Model
                




              click omnipy.components.remote.models.UrlPathModel_PurePosixPath href "" "omnipy.components.remote.models.UrlPathModel_PurePosixPath"
              click omnipy.components.remote.models.UrlPathModel href "" "omnipy.components.remote.models.UrlPathModel"
              click omnipy.data.model.Model href "" "omnipy.data.model.Model"
              click omnipy.data._mixins.display.ModelDisplayMixin href "" "omnipy.data._mixins.display.ModelDisplayMixin"
              click omnipy.data._mixins.display.BaseDisplayMixin href "" "omnipy.data._mixins.display.BaseDisplayMixin"
              click omnipy.data._data_class_creator.DataClassBase href "" "omnipy.data._data_class_creator.DataClassBase"

Type-checking helper combining path-model and path-like APIs.

This helper exists only for static typing to expose both UrlPathModel behavior and PurePosixPath operations.

Returned by:
Source code in src/omnipy/components/remote/models.py 
204
205
206
207
208
209
210
211
class UrlPathModel_PurePosixPath(UrlPathModel, PurePosixPath):  # type: ignore[misc]
    """Type-checking helper combining path-model and path-like APIs.

    This helper exists only for static typing to expose both
    ``UrlPathModel`` behavior and ``PurePosixPath`` operations.
    """

    ...