mtx-api-py 0.4.0__py3-none-any.whl

mtx_api/models/service.py

@@ -0,0 +1,207 @@
+from pydantic import AliasChoices, Field, RootModel
+
+from mtx_api.models.additional_data import AdditionalData
+from mtx_api.models.base import ImmutableBaseModel
+from mtx_api.models.typology import Typology
+
+
+class MandatoryInformantField(ImmutableBaseModel):
+    """
+    Represents a required field configuration for informant information.
+    This model defines which fields must be provided by the person reporting
+    a request, along with validation messages.
+    """
+
+    field: str | None = Field(
+        default=None,
+        description="The name of the field that is required (e.g., 'first_name', 'email').",
+    )
+    message: str | None = Field(
+        default=None,
+        description="The validation message if the field is missing or invalid.",
+    )
+    required: bool | None = Field(
+        default=None,
+        description="Whether this field is mandatory for submission.",
+    )
+
+
+class StatusNode(ImmutableBaseModel):
+    """
+    Represents a status node in the request lifecycle workflow.
+
+    Status nodes define the different stages a request can be in,
+    such as 'new', 'in progress', 'resolved', etc. They form a workflow
+    that tracks request progression.
+    """
+
+    status_node_type: str | None = Field(
+        default=None,
+        description=(
+            "The type of status node (e.g., 'initial_node', 'intermediate_node', 'final_node')."
+        ),
+    )
+    name: str | None = Field(
+        default=None,
+        description="Internal name of the status node.",
+    )
+    typology_node_id: str | None = Field(
+        default=None,
+        description="Identifier linking this status node to a typology node.",
+    )
+    visible_name: str | None = Field(
+        default=None,
+        description="Human-readable name given to users for this status.",
+    )
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the status node.",
+    )
+    order: int | None = Field(
+        default=None,
+        description="The showing order of this status in the workflow sequence.",
+    )
+    planned: bool | None = Field(
+        default=None,
+        description="Whether this status represents a planned or scheduled state.",
+    )
+
+
+class Service(ImmutableBaseModel):
+    """
+    Represents a service category for citizen reports.
+
+    A Service defines a specific category of issues or requests that citizens
+    can report to a jurisdiction. It configures what information is required from reporters,
+    upload requirements, visibility settings, the workflow status progression, etc.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the service.",
+    )
+    visible_name: str | None = Field(
+        default=None,
+        description="Human-readable name given to users.",
+    )
+    service_name: str | None = Field(
+        default=None,
+        description="Internal name of the service.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Detailed description of what the service provides.",
+    )
+    parent_service_name: str | None = Field(
+        default=None,
+        description="Name of the parent service if this is a sub-service.",
+    )
+    jurisdiction_code: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("jurisdiction_id", "jurisdiction_code"),
+        serialization_alias="jurisdiction_id",
+        description="Code of the jurisdiction where this service is available.",
+    )
+    typology: Typology | None = Field(
+        default=None,
+        description="The typology classification associated with this service.",
+    )
+    keywords: str | None = Field(
+        default=None,
+        description="Comma-separated keywords for searching and categorizing the service.",
+    )
+    mandatory_description: bool | None = Field(
+        default=None,
+        description=(
+            "Whether a text description is required when submitting a request for this service."
+        ),
+    )
+    mandatory_files: bool | None = Field(
+        default=None,
+        description="Whether file uploads are required when submitting a request for this service.",
+    )
+    mandatory_medias: bool | None = Field(
+        default=None,
+        description="Whether media uploads (images/videos) are required when submitting a request.",
+    )
+    max_upload_files: int | None = Field(
+        default=None,
+        description="Maximum number of files that can be uploaded with a request.",
+    )
+    max_upload_medias: int | None = Field(
+        default=None,
+        description="Maximum number of media items that can be uploaded with a request.",
+    )
+    public: bool | None = Field(
+        default=None,
+        description="Whether this service is publicly visible and available to all users.",
+    )
+    public_requests: bool | None = Field(
+        default=None,
+        description="Whether requests made for this service are publicly visible.",
+    )
+    deleted: bool | None = Field(
+        default=None,
+        description="Whether this service has been marked as deleted.",
+    )
+    social: bool | None = Field(
+        default=None,
+        description="Whether this service has social features enabled.",
+    )
+    evaluation: bool | None = Field(
+        default=None,
+        description="Whether users can evaluate or rate this service.",
+    )
+    hide_estimated_date: bool | None = Field(
+        default=None,
+        alias="hideEstimatedDate",
+        description="Whether to hide the estimated completion date from users.",
+    )
+    additional_data: AdditionalData | None = Field(
+        default=None,
+        alias="additionalData",
+        description="Additional configurable questions and data fields for this service.",
+    )
+    mandatory_informant_config: list[MandatoryInformantField] | None = Field(
+        default=None,
+        description="Configuration defining which informant fields are required.",
+    )
+    public_requests_internal: bool | None = Field(
+        default=None,
+        description="Whether requests are visible internally to authorized users.",
+    )
+    allow_changing_request_privacy: bool | None = Field(
+        default=None,
+        description="Whether users can change the privacy settings of their requests.",
+    )
+    service_code: str | None = Field(
+        default=None,
+        description="A unique code identifier for the service.",
+    )
+    status_node: list[StatusNode] | None = Field(
+        default=None,
+        description="List of status nodes defining the request lifecycle workflow.",
+    )
+    with_informant: bool | None = Field(
+        default=None,
+        description="Whether this service requires informant details.",
+    )
+    with_internal_informant: bool | None = Field(
+        default=None,
+        description="Whether this service supports internal informant submissions.",
+    )
+    with_authorized_internal_users: bool | None = Field(
+        default=None,
+        description="Whether authorized internal users can access this service.",
+    )
+
+
+class ServiceList(RootModel[list[Service]]):
+    """
+    A collection of Service objects.
+
+    This model represents a list of services returned when querying
+    available services for a jurisdiction.
+    """
+
+    pass

mtx_api/models/typology.py

@@ -0,0 +1,69 @@
+from pydantic import Field, RootModel
+
+from mtx_api.models.base import ImmutableBaseModel
+
+
+class Typology(ImmutableBaseModel):
+    """
+    Represents a classification or category for a service within the platform.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the typology.",
+    )
+    name: str | None = Field(
+        default=None,
+        description="Internal system name for the typology.",
+    )
+    visible_name: str | None = Field(
+        default=None,
+        description="Human-readable name of the typology given to the user.",
+    )
+    description_legend: str | None = Field(
+        default=None,
+        description="Short descriptive legend associated with the typology, "
+        "used to prompt the user when creating a request",
+    )
+    typology_description: str | None = Field(
+        default=None,
+        description="Describes the intent of the user when creating a request of this typology.",
+    )
+    order: int | None = Field(
+        default=None,
+        description="Numeric value used to determine the sorting order of the typology in lists.",
+    )
+    public: bool | None = Field(
+        default=None,
+        description="Flag indicating whether this typology is publicly accessible.",
+    )
+    has_location: bool | None = Field(
+        default=None,
+        alias="hasLocation",
+        description="Flag indicating if this typology requires or supports location data.",
+    )
+    location_type: str | None = Field(
+        default=None,
+        description="Specifies the type of location associated with this typology, if applicable."
+        "It can be one of: 'geolocation', 'indoor' or 'none'.",
+    )
+    with_description: bool | None = Field(
+        default=None,
+        description="Flag indicating if a description input is enabled when creating requests.",
+    )
+    with_files: bool | None = Field(
+        default=None,
+        description="Flag indicating if file attachments are supported for this typology.",
+    )
+    with_medias: bool | None = Field(
+        default=None,
+        description="Flag indicating if media (images/videos) support is enabled.",
+    )
+
+
+class TypologyList(RootModel[list[Typology]]):
+    """
+    A collection of Typology objects.
+    """
+
+    pass

mtx_api/settings.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class MTXSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="MTX_")
+
+    base_url: str | None = None
+    client_id: str | None = None
+    jwt_secret: str | None = None

mtx_api_py-0.4.0.dist-info/METADATA

@@ -0,0 +1,323 @@
+Metadata-Version: 2.4
+Name: mtx-api-py
+Version: 0.4.0
+Summary: SDK (wrapper) en Python para la API externa de MTX
+Project-URL: Repository, https://bitbucket.org/radmas/mtx_api_py
+Author-email: Álvaro Martín Rodríguez <alvaro.martin@radmas.com>
+License: MIT
+License-File: LICENSE.txt
+Keywords: api,mtx,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12.0
+Requires-Dist: httpx~=0.28.1
+Requires-Dist: pydantic-settings~=2.12.0
+Requires-Dist: pydantic~=2.12.4
+Requires-Dist: pyjwt~=2.10.1
+Description-Content-Type: text/markdown
+
+# MTX API PY
+
+Python SDK (wrapper) to consume the MTX API.
+
+## Installation
+
+```bash
+pip install mtx-api-py
+```
+
+## Quick start
+
+```python
+import asyncio
+from mtx_api import MTXClient
+
+
+async def main():
+    async with MTXClient(
+            base_url="https://api.mtx.example.com",
+            client_id="YOUR_CLIENT_ID",
+            jwt_secret="BASE64_SECRET",  # optional; only if you will use auth.login_jwt
+    ) as client:
+        ok = await client.base.status(access_token="<ACCESS_TOKEN>")
+        print(ok)
+
+
+asyncio.run(main())
+```
+
+## Configure via environment variables (.env)
+
+You can configure the client using environment variables or a `.env` file at the project root:
+
+```bash
+# .env
+MTX_BASE_URL=https://api.mtx.example.com
+MTX_CLIENT_ID=YOUR_CLIENT_ID
+MTX_JWT_SECRET=BASE64_SECRET # Optional: only needed if you will use login_jwt
+```
+
+```python
+import asyncio
+from mtx_api import MTXClient
+from dotenv import load_dotenv
+
+load_dotenv()  # Load environment variables from .env
+
+
+async def main():
+    async with MTXClient() as client:
+        ok = await client.base.status(access_token="<ACCESS_TOKEN>")
+        print(ok)
+
+
+asyncio.run(main())
+```
+
+## Available functions
+
+All available functions accept their parameters as keyword arguments.
+You can omit arguments that are not needed and accept None.
+
+### client.base:
+
+```
+status(
+  access_token: str | None
+) -> bool
+```
+```
+openapi() -> str
+```
+
+### client.auth:
+
+```
+login_anonymous(
+  device_id: str
+) -> Authentication
+```
+```
+login_jwt(
+  email: str,
+  first_name: str | None,
+  last_name: str | None,
+  register: bool | None,
+  legal_terms_accepted: bool | None
+) -> Authentication
+```
+```
+login_refresh(
+  refresh_token: str
+) -> Authentication
+```
+```
+register(
+  username: str,
+  password: str,
+  first_name: str,
+  last_name: str,
+  legal_terms_accepted: bool,
+  jurisdiction_code: str | None
+) -> Authentication
+```
+```
+login(
+  username: str,
+  password: str
+) -> Authentication
+```
+
+### client.user:
+
+```
+profile(
+  access_token: str | None
+) -> Profile
+```
+```
+update_profile(
+  access_token: str | None,
+  email: str | None,
+  username: str | None,
+  first_name: str | None,
+  last_name: str | None,
+  twitter_nickname: str | None,
+  phone: str | None,
+  gender: str | None,
+  birthday: str | None
+) -> Profile
+```
+
+```
+accept_terms(
+  access_token: str
+) -> bool
+```
+```
+legal_terms() -> LegalTerms
+```
+
+### client.services:
+
+```
+list(
+  access_token: str | None,
+  jurisdiction_codes: list[str],
+  lat: float | None,
+  lng: float | None,
+  typology_ids: list[str] | None
+) -> ServiceList
+```
+```
+detail(
+  access_token: str | None,
+  service_id: str,
+  jurisdiction_code: str
+) -> Service
+```
+
+### client.typologies:
+
+```
+list(
+  access_token: str | None,
+  jurisdiction_codes: list[str],
+  jurisdiction_element_id: str | None,
+  typology_ids: list[str] | None,
+  lat: float | None,
+  lng: float | None,
+  page: int | None,
+  limit: int | None
+) -> TypologyList
+```
+### client.jurisdictions:
+```
+list(
+  access_token: str | None,
+  lat: float | None,
+  lng: float | None
+) -> JurisdictionList
+```
+```
+detail(
+  access_token: str | None,
+  jurisdiction_code: str
+) -> Jurisdiction
+```
+### client.jurisdiction_elements:
+```
+list(
+  access_token: str | None,
+  jurisdiction_code: str
+) -> JurisdictionElementList
+```
+
+### client.location:
+```
+resolve(
+  jurisdiction_element_id: str,
+  formatted_address: str | None,
+  lat: float | None,
+  lng: float | None
+) -> LocationAdditionalDataList
+```
+
+### client.requests:
+
+```
+list(
+  access_token: str | None,
+  jurisdiction_codes: list[str] | None,
+  service_request_ids: list[str] | None,
+  service_ids: list[str] | None,
+  start_date: str | None,
+  end_date: str | None,
+  own: bool | None,
+  lat: float | None,
+  lng: float | None,
+  page: int | None,
+  limit: int | None,
+  address_and_service_request_id: str | None,
+  status: list[str] | None,
+  typology_ids: list[str] | None,
+  distance: int | None,
+  following: bool | None,
+  order: str | None,
+  complaints: bool | None,
+  reiterations: bool | None,
+  user_reiterated: bool | None,
+  user_complaint: bool | None,
+  jurisdiction_element_ids: list[str] | None,
+  level: int | None,
+  polygon: list[float] | None,
+  final_ok: bool | None,
+  final_not_ok: bool | None,
+  final_status: bool | None,
+  interested: bool | None,
+  timezone: str | None
+) -> RequestList
+```
+```
+detail(
+  access_token: str | None,
+  request_id: str
+) -> Request
+```
+```
+create(
+  access_token: str | None,
+  service_id: str,
+  jurisdiction_code: str,
+  jurisdiction_element_id: str | None,
+  origin_device_id: str | None,
+  description: str | None,
+  public: bool | None,
+  lat: float | None,
+  lng: float | None,
+  address_string: str | None,
+  email: str | None,
+  first_name: str | None,
+  last_name: str | None,
+  phone: str | None,
+  twitter_nickname: str | None,
+  additional_data: Sequence[AdditionalDataValue] | None
+) -> CreatedRequest
+```
+```
+attach_media(
+  access_token: str | None,
+  request_id: str,
+  jurisdiction_code: str,
+  file: tuple[str, bytes]
+) -> RequestMedia
+```
+```
+attach_comment(
+  access_token: str | None,
+  request_id: str,
+  comment: str | None,
+  files: Sequence[tuple[str, bytes]]
+) -> RequestComment
+```
+
+## Errors
+
+- HTTP errors raise `ApiError` with fields `status_code`, `code`, and `description`.
+- Response model decoding/validation errors raise `ApiDecodingError`.
+- SDK parameter validation errors raise specific exceptions (all extend `ValueError`):
+  - `MissingBaseUrlError`: missing `base_url` configuration (via `MTX_BASE_URL` or `base_url` parameter).
+  - `MissingClientIdError`: missing `client_id` configuration (via `MTX_CLIENT_ID` or `client_id` parameter).
+  - `MissingJwtSecretError`: missing JWT secret configuration (via `MTX_JWT_SECRET` or `jwt_secret` parameter) when using `auth.login_jwt`.
+  - `MissingJurisdictionCodesError`: missing `jurisdiction_codes`/`jurisdiction_code` in calls that require it.
+  - `MissingServiceIdError`: missing `service_id` in calls that require it.
+  - `MissingRequestIdError`: missing `request_id` in calls that require it.
+  - `MissingArgumentError`: a required argument is missing.
+  - `InvalidEmailError`: the email is not valid.

mtx_api_py-0.4.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+mtx_api/__init__.py,sha256=iYbppDpBJAKmAZbLJ5cq_GW2KZmo4QU53Ux8pmMg4WM,535
+mtx_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mtx_api/settings.py,sha256=Er8CgeyLIWackgKozoLWe_Jnv7lL_lfvKLhlwqSTb_Y,291
+mtx_api/client/__init__.py,sha256=vFT4n8Uu34_30JNo2QI3Uh4wL0Yhs8mcDEEgdZ76-ew,73
+mtx_api/client/_auth_client.py,sha256=644gdPGGSlLs9EyD6HVZBoWiJ0Kecgf_7-8t8bY2GMM,7725
+mtx_api/client/_base_client.py,sha256=CtQFWDL-cba5JXxpJmmaiTqQlSwI4no0hZv1Q5Mo4KI,1573
+mtx_api/client/_jurisdiction_client.py,sha256=ZYkLpSu2GwBbi3ZI_VgkMqZUcQXYnhOTg6-B9LcQI_o,2708
+mtx_api/client/_jurisdiction_elements_client.py,sha256=6sZMh3VtiPmZ-dDSTHZj4V7o2xklCu3EXGU1W_Y08-Y,1531
+mtx_api/client/_location_client.py,sha256=OFFl0yhutOiz_vTvd0Rm46LZwnLj_2BSJ5Merl2bzkc,2807
+mtx_api/client/_mtx_http_client.py,sha256=Z_hSw-auehVe-R5_9_Oxlr-1xWNpvFv18hXIJUGvRqw,6608
+mtx_api/client/_request_client.py,sha256=Ku8wuvu3GAxtWBi949pZYbLVAeHFY1OTVkLjIHWp-T4,15245
+mtx_api/client/_service_client.py,sha256=cAJTCSUOSiZKpePhn9j-aLY0sKPuNqygYexQK-M6fZA,3461
+mtx_api/client/_typology_client.py,sha256=Z3WW6WDUOTX9hlkv0DkMfxgMo-Rn2mL2lhqcx4gEATw,2514
+mtx_api/client/_user_client.py,sha256=Uk4qF8-bqRWdOwfEDR_hRsJcgGUuA255YFAofqJZEv8,5033
+mtx_api/client/mtx_client.py,sha256=wKMyNJXuFbFCO6FJ313Ixad4nI-5QGSgE_I4ez7w2LY,1935
+mtx_api/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mtx_api/models/additional_data.py,sha256=LfLwVOwdj616BG20fzXAiWhQeIxDVlrOXiUyHlRBrcY,10843
+mtx_api/models/auth.py,sha256=K5GD-HN4szBepU8E8B8tMlluwKtvSLsYe8WiqmtQh0I,2831
+mtx_api/models/base.py,sha256=1v_evJGBIZlGNGvlvQKGgVxLuB4hsLapPhbJNULyiNs,448
+mtx_api/models/common.py,sha256=ADopwxoQqXuzloIZCx4tTnJMLd0rFwgSngfTnnGTd8o,3043
+mtx_api/models/errors.py,sha256=ehuHh3j2hAFzrFXsxDPLKjNZd1cyRyjr8l_TbeNTsjs,3228
+mtx_api/models/jurisdiction.py,sha256=CU7N6QCvsjTcQ4QlSjohW0h-qIDPQ5eTrH5cR-Ps-RU,2933
+mtx_api/models/medias.py,sha256=vn4LRH5-p2MWWu2wi7KasPNelV5cnONA0wVHhhAhzZo,3170
+mtx_api/models/request.py,sha256=kZswmrySyrm7ik8OcU0__jZBn2PIvF3xQymo51avwhk,8673
+mtx_api/models/request_comment.py,sha256=xja_rjWm4gHvlIdpdPz31srmSGrx05N3onbfATt87TM,1706
+mtx_api/models/request_media.py,sha256=Lnk_KHBLBSIoaIsMP7NRpFB1oNzhbG2ZDK5DiskBdyU,1025
+mtx_api/models/service.py,sha256=ZMKVpI15JEnbUqBeNG2yv5O7p_ckrrwP0aMN3_1iZpM,7282
+mtx_api/models/typology.py,sha256=6KvxRpl9Y3JgBS0QVKpX2DZR5_tvJ14fHjLDdXBKCI4,2294
+mtx_api_py-0.4.0.dist-info/METADATA,sha256=iV2Dfv9Ic0N4OJ4WpBIVYgR44NC5sJYSfxVsW8tbubs,7115
+mtx_api_py-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mtx_api_py-0.4.0.dist-info/licenses/LICENSE.txt,sha256=ZLROmkgKwdLBPR2aFrjVZIxbJMNEc_2QMYuAlAnnBq8,1080
+mtx_api_py-0.4.0.dist-info/RECORD,,

mtx_api_py-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mtx_api_py-0.4.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Radmas Technologies S.L.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.