getrak-python-sdk 1.0.0__tar.gz → 1.2.0__tar.gz

{getrak_python_sdk-1.0.0/src/getrak_python_sdk.egg-info → getrak_python_sdk-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getrak-python-sdk
-Version: 1.0.0
+Version: 1.2.0
 Summary: Client de comunicaçao c/ API da Getrak
 Author-email: Filipe Coelho <filipe@fmconsult.com.br>
 License: MIT License
@@ -18,4 +18,6 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: fmconsult-utils-python-sdk>=2.2.0
+Requires-Dist: jsonpickle>=3.0
 Dynamic: license-file

{getrak_python_sdk-1.0.0 → getrak_python_sdk-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "getrak-python-sdk"
-version = "1.0.0"
+version = "1.2.0"
 description = "Client de comunicaçao c/ API da Getrak"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -19,7 +19,13 @@ classifiers = [
   "Operating System :: OS Independent",
 ]
 
-dependencies = []
+dependencies = [
+  "fmconsult-utils-python-sdk>=2.2.0",
+  "jsonpickle>=3.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
 
 [project.urls]
 "Homepage" = "https://github.com/seuuser/minha-biblioteca"

getrak_python_sdk-1.2.0/src/getrak/api.py

@@ -0,0 +1,151 @@
+import json
+import logging
+import os
+import threading
+import time
+from http import HTTPMethod
+
+from fmconsult.exceptions.bad_request_exception import BadRequestException
+from fmconsult.exceptions.forbidden_exception import ForbiddenException
+from fmconsult.exceptions.unauthorized_exception import UnauthorizedException
+from fmconsult.http.api import ApiBase, ContentType
+from fmconsult.utils.url import UrlUtil
+
+from getrak.errors import AuthenticationFailed, GetrakError
+
+log = logging.getLogger(__name__)
+
+AUTH_REJECTED = (BadRequestException, UnauthorizedException, ForbiddenException)
+
+
+class GetrakApi(ApiBase):
+    """Cliente da API Getrak.
+
+    Sem argumentos, lê `getrak.api.auth_code`, `getrak.api.login`, `getrak.api.password`
+    e `getrak.api.grant_type` e autentica na construção, como antes. Usuário e senha vão
+    no corpo do POST. Os demais argumentos são opcionais e servem para reutilizar um
+    token, limitar a taxa e tentar de novo em falha passageira.
+    """
+
+    def __init__(
+        self,
+        *,
+        auth_code=None,
+        login=None,
+        password=None,
+        grant_type=None,
+        base_url=None,
+        rate_limiter=None,
+        retry_transient=False,
+        authenticate_on_init=True,
+        verbose=True,
+        sleep=None,
+        clock=None,
+        max_attempts=5,
+        on_rate_limited=None,
+        on_token=None,
+        log_requests=True,
+        timeout=60,
+    ):
+        self.api_auth_code = auth_code if auth_code is not None else os.environ["getrak.api.auth_code"]
+        self.api_login = login if login is not None else os.environ["getrak.api.login"]
+        self.api_password = password if password is not None else os.environ["getrak.api.password"]
+        self.api_grant_type = grant_type if grant_type is not None else os.environ["getrak.api.grant_type"]
+        self.base_url = (base_url or "https://api.getrak.com").rstrip("/")
+        self.verbose = verbose
+        self._rate_limiter = rate_limiter
+        self._retry_transient = retry_transient
+        self._max_attempts = max_attempts
+        self._sleep = sleep or time.sleep
+        self._clock = clock or time.monotonic
+        self._on_rate_limited = on_rate_limited
+        self._on_token = on_token
+        self._log_requests = log_requests
+        self._timeout = timeout
+        self._auth_failed = False
+        self._token = None
+        self._token_type = "Bearer"
+        self._token_lock = threading.Lock()
+        self.requests = 0
+        self.rate_limited = 0
+        self.last_http_attempts = 0
+        self.current_operation = None
+        self.headers = {"Authorization": f"Basic {self.api_auth_code}"}
+        if authenticate_on_init:
+            self._ensure_token()
+
+    def _raise_if_auth_failed(self):
+        if self._auth_failed:
+            raise AuthenticationFailed("autenticação na Getrak já foi recusada nesta execução")
+
+    def _ensure_token(self):
+        with self._token_lock:
+            self._raise_if_auth_failed()
+            if self._token is None:
+                self._token = self._authenticate()
+            return self._token
+
+    def _renew_token(self, stale):
+        with self._token_lock:
+            self._raise_if_auth_failed()
+            if self._token is None or self._token == stale:
+                self._token = self._authenticate()
+            return self._token
+
+    def _authenticate(self):
+        if self.verbose:
+            log.info("api authentication...")
+        self.current_operation = "autenticação"
+        self.headers = {"Authorization": f"Basic {self.api_auth_code}"}
+        url = UrlUtil().make_url(self.base_url, ["newkoauth", "oauth", "token"])
+        try:
+            raw = self.call_request(
+                HTTPMethod.POST,
+                url,
+                payload={
+                    "username": self.api_login,
+                    "password": self.api_password,
+                    "grant_type": self.api_grant_type,
+                },
+                content_type=ContentType.FORM_URLENCODED,
+                request_timeout=self._timeout,
+            )
+        except AUTH_REJECTED:
+            self._auth_failed = True
+            raise AuthenticationFailed(
+                "Getrak recusou a autenticação; verifique usuário, senha e a credencial do cliente"
+            ) from None
+        try:
+            data = json.loads(raw)
+            token = data["access_token"]
+        except (ValueError, KeyError, TypeError):
+            raise GetrakError("resposta de autenticação da Getrak sem access_token") from None
+        if not isinstance(token, str) or not token:
+            raise GetrakError("resposta de autenticação da Getrak sem access_token")
+        if isinstance(data, dict) and data.get("error"):
+            raise AuthenticationFailed("Getrak recusou a autenticação")
+        token_type = str(data.get("token_type") or "Bearer")
+        self._token_type = "Bearer" if token_type.lower() == "bearer" else token_type
+        self.headers = {"Authorization": f"{self._token_type} {token}"}
+        if self._on_token is not None:
+            self._on_token(token)
+        return token
+
+    def _get(self, url, token, operation):
+        self.current_operation = operation
+        self.headers = {"Authorization": f"{self._token_type} {token}"}
+        return self.call_request(HTTPMethod.GET, url, request_timeout=self._timeout)
+
+    def _authorized(self, url, operation):
+        attempts = 0
+        token = self._ensure_token()
+        try:
+            raw = self._get(url, token, operation)
+        except UnauthorizedException:
+            attempts += self.last_http_attempts
+            token = self._renew_token(token)
+            raw = self._get(url, token, operation)
+            attempts += self.last_http_attempts
+            return raw, attempts
+        attempts += self.last_http_attempts
+        return raw, attempts

getrak_python_sdk-1.2.0/src/getrak/apis/recebidos.py

@@ -0,0 +1,45 @@
+import json
+import logging
+import re
+
+import jsonpickle
+from http import HTTPMethod
+from fmconsult.utils.url import UrlUtil
+from getrak.api import GetrakApi
+from getrak.errors import GetrakError, InvalidVehicleId, VehicleNotFound
+
+VEHICLE_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+class Recebidos(GetrakApi):
+
+  def get(self, id_veiculo, data_inicio, data_fim):
+    logging.info(f'get vehicle {id_veiculo} records from {data_inicio} to {data_fim}...')
+    res = self.call_request(
+      http_method=HTTPMethod.GET, 
+      request_url=UrlUtil().make_url(self.base_url, ['v0.1','recebidos', id_veiculo, data_inicio, data_fim])
+    )    
+    return jsonpickle.decode(res)
+
+  def fetch(self, vehicle_id, start, end):
+    """Busca as posições já autenticando sob demanda. Devolve `(lista, tentativas HTTP)`.
+
+    Valida o ID aqui. `get` continua aceitando o valor que o chamador passar.
+    """
+    if not isinstance(vehicle_id, str) or VEHICLE_ID_RE.fullmatch(vehicle_id) is None:
+      raise InvalidVehicleId("ID de veículo Getrak inválido")
+    url = UrlUtil().make_url(self.base_url, ["v0.1", "recebidos", vehicle_id, start, end])
+    raw, attempts = self._authorized(url, "recebidos")
+    try:
+      body = json.loads(raw)
+    except ValueError:
+      raise GetrakError("resposta de recebidos não é JSON") from None
+    if isinstance(body, dict):
+      message = body.get("error") if isinstance(body.get("error"), str) else ""
+      if "não encontrado" in message.casefold():
+        raise VehicleNotFound(message)
+    if not isinstance(body, list):
+      raise GetrakError("resposta de recebidos não é uma lista")
+    if not all(isinstance(item, dict) for item in body):
+      raise GetrakError("resposta de recebidos contém itens que não são objetos")
+    return body, attempts

getrak_python_sdk-1.2.0/src/getrak/errors.py

@@ -0,0 +1,14 @@
+class GetrakError(Exception):
+    """Erro da integração com a Getrak."""
+
+
+class InvalidVehicleId(GetrakError):
+    pass
+
+
+class VehicleNotFound(GetrakError):
+    """A conta não tem esse veículo. Não há lista de posições para gravar."""
+
+
+class AuthenticationFailed(GetrakError):
+    """A Getrak recusou as credenciais. Vale para as chamadas seguintes desta instância."""

{getrak_python_sdk-1.0.0 → getrak_python_sdk-1.2.0/src/getrak_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getrak-python-sdk
-Version: 1.0.0
+Version: 1.2.0
 Summary: Client de comunicaçao c/ API da Getrak
 Author-email: Filipe Coelho <filipe@fmconsult.com.br>
 License: MIT License
@@ -18,4 +18,6 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: fmconsult-utils-python-sdk>=2.2.0
+Requires-Dist: jsonpickle>=3.0
 Dynamic: license-file

{getrak_python_sdk-1.0.0 → getrak_python_sdk-1.2.0}/src/getrak_python_sdk.egg-info/SOURCES.txt

@@ -1,9 +1,9 @@
 LICENSE
 README.md
 pyproject.toml
-src/__init__.py
 src/getrak/__init__.py
 src/getrak/api.py
+src/getrak/errors.py
 src/getrak/apis/__init__.py
 src/getrak/apis/localizacoes.py
 src/getrak/apis/recebidos.py
@@ -14,4 +14,6 @@ src/getrak/database/models/vehicle.py
 src/getrak_python_sdk.egg-info/PKG-INFO
 src/getrak_python_sdk.egg-info/SOURCES.txt
 src/getrak_python_sdk.egg-info/dependency_links.txt
-src/getrak_python_sdk.egg-info/top_level.txt
+src/getrak_python_sdk.egg-info/requires.txt
+src/getrak_python_sdk.egg-info/top_level.txt
+tests/test_client.py

getrak_python_sdk-1.2.0/src/getrak_python_sdk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+fmconsult-utils-python-sdk>=2.2.0
+jsonpickle>=3.0

getrak_python_sdk-1.2.0/src/getrak_python_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+getrak

getrak_python_sdk-1.2.0/tests/test_client.py

@@ -0,0 +1,138 @@
+import base64
+from urllib.parse import parse_qs
+
+import pytest
+import responses
+from responses import registries
+
+from getrak.apis.recebidos import Recebidos
+from getrak.errors import AuthenticationFailed, GetrakError, InvalidVehicleId, VehicleNotFound
+
+BASE = "https://api.getrak.com"
+AUTH = f"{BASE}/newkoauth/oauth/token"
+POS = f"{BASE}/v0.1/recebidos/12345/2026-10-04T03:00:00/2026-10-05T02:59:59"
+PASSWORD = "SenhaSuperSecreta123"
+AUTH_CODE = base64.b64encode(b"cliente:segredo").decode()
+
+
+@pytest.fixture
+def env(monkeypatch):
+    monkeypatch.setenv("getrak.api.auth_code", AUTH_CODE)
+    monkeypatch.setenv("getrak.api.login", "usuario")
+    monkeypatch.setenv("getrak.api.password", PASSWORD)
+    monkeypatch.setenv("getrak.api.grant_type", "password")
+
+
+def test_recebidos_keeps_constructor_and_sends_password_in_the_body(env):
+    with responses.RequestsMock(registry=registries.OrderedRegistry) as http:
+        http.add(responses.POST, AUTH, json={"access_token": "tok", "token_type": "bearer"}, status=200)
+        http.add(responses.GET, POS, json=[{"lat": 1}], status=200)
+        records = Recebidos().get("12345", "2026-10-04T03:00:00", "2026-10-05T02:59:59")
+        sent = http.calls[0].request
+        assert "password" not in sent.url
+        assert parse_qs(sent.body)["password"] == [PASSWORD]
+        assert sent.headers["Authorization"] == f"Basic {AUTH_CODE}"
+        assert http.calls[1].request.headers["Authorization"] == "Bearer tok"
+
+    assert records == [{"lat": 1}]
+
+
+def test_password_is_not_logged(env, caplog):
+    caplog.set_level("INFO")
+    with responses.RequestsMock() as http:
+        http.add(
+            responses.POST,
+            AUTH,
+            json={"access_token": "tok-secreto-xyz", "token_type": "bearer"},
+            status=200,
+        )
+        Recebidos()
+    assert PASSWORD not in caplog.text
+    assert "tok-secreto-xyz" not in caplog.text
+
+
+def test_fetch_reuses_token_and_rejects_bad_id():
+    sleeps = []
+    with responses.RequestsMock(registry=registries.OrderedRegistry) as http:
+        http.add(responses.POST, AUTH, json={"access_token": "tok-1", "token_type": "Bearer"}, status=200)
+        http.add(responses.GET, POS, json=[{"a": 1}], status=200)
+        client = Recebidos(
+            auth_code=AUTH_CODE,
+            login="usuario",
+            password=PASSWORD,
+            grant_type="password",
+            authenticate_on_init=False,
+            verbose=False,
+            log_requests=False,
+            retry_transient=True,
+            sleep=sleeps.append,
+        )
+        with pytest.raises(InvalidVehicleId):
+            client.fetch("12/34", "2026-10-04T03:00:00", "2026-10-05T02:59:59")
+        assert len(http.calls) == 0
+        positions, attempts = client.fetch("12345", "2026-10-04T03:00:00", "2026-10-05T02:59:59")
+        posts = [call for call in http.calls if call.request.method == "POST"]
+
+    assert positions == [{"a": 1}]
+    assert attempts == 1
+    assert len(posts) == 1
+
+
+def test_rejected_credentials_are_not_retried():
+    with responses.RequestsMock() as http:
+        http.add(responses.POST, AUTH, status=401)
+        client = Recebidos(
+            auth_code=AUTH_CODE,
+            login="usuario",
+            password=PASSWORD,
+            grant_type="password",
+            authenticate_on_init=False,
+            verbose=False,
+            log_requests=False,
+            retry_transient=True,
+        )
+        with pytest.raises(AuthenticationFailed):
+            client.fetch("12345", "inicio", "fim")
+        with pytest.raises(AuthenticationFailed):
+            client.fetch("12345", "inicio", "fim")
+        assert len(http.calls) == 1
+        assert PASSWORD not in str(http.calls[0].request.url)
+
+
+def test_non_list_is_an_error():
+    with responses.RequestsMock() as http:
+        http.add(responses.POST, AUTH, json={"access_token": "tok"}, status=200)
+        http.add(responses.GET, POS, json={"erro": "x"}, status=200)
+        client = Recebidos(
+            auth_code=AUTH_CODE,
+            login="usuario",
+            password=PASSWORD,
+            grant_type="password",
+            authenticate_on_init=False,
+            verbose=False,
+            log_requests=False,
+        )
+        with pytest.raises(GetrakError):
+            client.fetch("12345", "2026-10-04T03:00:00", "2026-10-05T02:59:59")
+
+
+def test_unknown_vehicle_is_a_specific_error():
+    with responses.RequestsMock() as http:
+        http.add(responses.POST, AUTH, json={"access_token": "tok"}, status=200)
+        http.add(
+            responses.GET,
+            POS,
+            json={"error": "Veículo não encontrado para o cliente informado", "status": 404},
+            status=200,
+        )
+        client = Recebidos(
+            auth_code=AUTH_CODE,
+            login="usuario",
+            password=PASSWORD,
+            grant_type="password",
+            authenticate_on_init=False,
+            verbose=False,
+            log_requests=False,
+        )
+        with pytest.raises(VehicleNotFound):
+            client.fetch("12345", "2026-10-04T03:00:00", "2026-10-05T02:59:59")

getrak_python_sdk-1.0.0/src/getrak/api.py

@@ -1,46 +0,0 @@
-import logging, os, jsonpickle
-from http import HTTPMethod
-from fmconsult.http.api import ApiBase
-from fmconsult.utils.url import UrlUtil
-
-class GetrakApi(ApiBase):
-
-	def __init__(self):
-		try:
-			self.api_auth_code 	= os.environ['getrak.api.auth_code']
-			self.api_login 		= os.environ['getrak.api.login']
-			self.api_password 	= os.environ['getrak.api.password']
-			self.api_grant_type = os.environ['getrak.api.grant_type']
-
-			self.base_url = 'https://api.getrak.com'
-			self.headers = {
-				'Authorization': f'Basic {self.api_auth_code}'
-			}
-
-			self.__login()
-		except:
-			raise
-	
-	def __login(self):
-		try:
-			logging.info('api authentication...')
-			res = self.call_request(
-				http_method=HTTPMethod.POST, 
-				request_url=UrlUtil().make_url(self.base_url, ['newkoauth','oauth','token']), 
-				params={
-					'username': self.api_login, 
-					'password': self.api_password,
-					'grant_type': self.api_grant_type
-				}
-			)
-			res = jsonpickle.decode(res)
-			if not('error' in res):
-				self.token_type = res['token_type']
-				self.access_token = res['access_token']
-				self.headers = {
-					'Authorization': f'{self.token_type} {self.access_token}'
-				}
-			else:
-				raise Exception(res['error_description'])
-		except:
-			raise

getrak_python_sdk-1.0.0/src/getrak/apis/recebidos.py

@@ -1,14 +0,0 @@
-import logging, jsonpickle
-from http import HTTPMethod
-from fmconsult.utils.url import UrlUtil
-from getrak.api import GetrakApi
-
-class Recebidos(GetrakApi):
-
-  def get(self, id_veiculo, data_inicio, data_fim):
-    logging.info(f'get vehicle {id_veiculo} records from {data_inicio} to {data_fim}...')
-    res = self.call_request(
-      http_method=HTTPMethod.GET, 
-      request_url=UrlUtil().make_url(self.base_url, ['v0.1','recebidos', id_veiculo, data_inicio, data_fim])
-    )    
-    return jsonpickle.decode(res)

getrak_python_sdk-1.0.0/src/getrak_python_sdk.egg-info/top_level.txt

@@ -1,2 +0,0 @@
-__init__
-getrak