roberty-code 0.1.0__py3-none-any.whl

roberty_code/__init__.py

@@ -0,0 +1,52 @@
+"""
+SDK oficial para Code Projects da Roberty.
+
+    import roberty_code as roberty
+
+    cpf = roberty.input("cpf")
+    roberty.output({"status": "ok"})
+"""
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from . import context as _context
+from ._env import ENV_VARS
+from .errors import RobertyArgsError, RobertyOutputError
+from .exception import ExceptionDetails, exception
+from .inputs import input, inputs  # noqa: A004
+from .output import output
+from .run import run
+
+__all__ = [
+    "ENV_VARS",
+    "ExceptionDetails",
+    "RobertyArgsError",
+    "RobertyOutputError",
+    "environment",
+    "exception",
+    "input",
+    "inputs",
+    "is_roberty",
+    "output",
+    "run",
+    "trigger",
+]
+
+if TYPE_CHECKING:
+    trigger: Optional[str]
+    environment: Optional[str]
+    is_roberty: bool
+
+_DYNAMIC = {
+    "trigger": _context.trigger,
+    "environment": _context.environment,
+    "is_roberty": _context.is_roberty,
+}
+
+
+def __getattr__(name: str) -> Any:
+    """`trigger`, `environment` e `is_roberty` são lidos da env a cada acesso."""
+    getter = _DYNAMIC.get(name)
+    if getter is None:
+        raise AttributeError(f"module 'roberty_code' has no attribute '{name}'")
+    return getter()

roberty_code/_args_file.py

@@ -0,0 +1,24 @@
+import json
+import os
+from typing import Any
+
+from ._env import ENV_VARS
+from .errors import RobertyArgsError
+
+_cache: dict[str, Any] = {}
+
+
+def read_args_file() -> Any:
+    """Lê (com cache) o JSON apontado por `roberty-args-file-path`; `None` sem a variável."""
+    file_path = os.environ.get(ENV_VARS["args_file_path"])
+    if not file_path:
+        return None
+    if file_path in _cache:
+        return _cache[file_path]
+    try:
+        with open(file_path, encoding="utf-8") as file:
+            parsed = json.load(file)
+    except (OSError, ValueError) as cause:
+        raise RobertyArgsError(file_path, cause) from cause
+    _cache[file_path] = parsed
+    return parsed

roberty_code/_env.py

@@ -0,0 +1,8 @@
+"""Nomes das variáveis de ambiente injetadas pela Roberty."""
+
+ENV_VARS = {
+    "environment": "roberty-environment",
+    "trigger": "roberty-trigger",
+    "args_file_path": "roberty-args-file-path",
+    "output_file_path": "roberty-output-file-path",
+}

roberty_code/context.py

@@ -0,0 +1,19 @@
+import os
+from typing import Optional
+
+from ._env import ENV_VARS
+
+
+def trigger() -> Optional[str]:
+    """`manual`, `schedule`, `webhook` ou `evaluation`. `None` fora da Roberty."""
+    return os.environ.get(ENV_VARS["trigger"])
+
+
+def environment() -> Optional[str]:
+    """`production` ou `preview`. `None` fora da Roberty."""
+    return os.environ.get(ENV_VARS["environment"])
+
+
+def is_roberty() -> bool:
+    """`True` quando o processo roda na Roberty."""
+    return bool(os.environ.get(ENV_VARS["trigger"]))

roberty_code/errors.py

@@ -0,0 +1,15 @@
+class RobertyArgsError(Exception):
+    """O arquivo de argumentos existe mas não pôde ser lido como JSON."""
+
+    def __init__(self, file_path: str, cause: BaseException) -> None:
+        super().__init__(
+            f'Roberty: não foi possível ler os argumentos em "{file_path}": {cause}'
+        )
+        self.file_path = file_path
+
+
+class RobertyOutputError(Exception):
+    """O resultado não pôde ser serializado como JSON."""
+
+    def __init__(self, cause: BaseException) -> None:
+        super().__init__(f"Roberty: o resultado não pôde ser serializado como JSON: {cause}")

roberty_code/exception.py

@@ -0,0 +1,22 @@
+from typing import Optional, TypedDict
+
+from ._args_file import read_args_file
+
+
+class ExceptionDetails(TypedDict):
+    message: str
+    stack: Optional[str]
+    exitCode: int
+
+
+def exception() -> Optional[ExceptionDetails]:
+    """Detalhes do erro dentro do `exceptionHandler`. `None` fora dele."""
+    details = read_args_file()
+    if not isinstance(details, dict):
+        return None
+    stack = details.get("stack")
+    return ExceptionDetails(
+        message=str(details.get("message", "")),
+        stack=stack if isinstance(stack, str) else None,
+        exitCode=int(details.get("exitCode", 1)),
+    )

roberty_code/inputs.py

@@ -0,0 +1,22 @@
+from typing import Any, Optional, TypeVar, Union, overload
+
+from ._args_file import read_args_file
+
+T = TypeVar("T")
+
+
+def inputs() -> Optional[Any]:
+    """Todos os argumentos da execução (`webhook`/`evaluation`). `None` em `manual`/`schedule`."""
+    return read_args_file()
+
+
+@overload
+def input(name: str) -> Optional[Any]: ...  # noqa: A001
+@overload
+def input(name: str, default: T) -> Union[Any, T]: ...  # noqa: A001
+def input(name: str, default: Any = None) -> Any:  # noqa: A001
+    """Um argumento específico. `default` quando não existe ou não há argumentos."""
+    args = read_args_file()
+    if not isinstance(args, dict):
+        return default
+    return args.get(name, default)

roberty_code/output.py

@@ -0,0 +1,47 @@
+import json
+import os
+import sys
+from typing import Any
+
+from ._env import ENV_VARS
+from .errors import RobertyOutputError
+
+OUTPUT_LIMIT_BYTES = 256 * 1024
+
+_state = {"warned_missing_path": False}
+
+
+def output(value: Any) -> bool:
+    """Grava `value` como JSON no arquivo de resultado; `False` fora da Roberty (aviso único)."""
+    serialized = _serialize(value)
+    file_path = os.environ.get(ENV_VARS["output_file_path"])
+    if not file_path:
+        _warn_missing_path_once()
+        return False
+    if len(serialized.encode("utf-8")) > OUTPUT_LIMIT_BYTES:
+        print(
+            "Roberty: resultado acima de 256 KB; "
+            "em execuções webhook a plataforma corta o excedente.",
+            file=sys.stderr,
+        )
+    with open(file_path, "w", encoding="utf-8") as file:
+        file.write(serialized)
+    return True
+
+
+def _serialize(value: Any) -> str:
+    try:
+        return json.dumps(value, ensure_ascii=False)
+    except (TypeError, ValueError) as cause:
+        raise RobertyOutputError(cause) from cause
+
+
+def _warn_missing_path_once() -> None:
+    if _state["warned_missing_path"]:
+        return
+    _state["warned_missing_path"] = True
+    print(
+        f'Roberty: "{ENV_VARS["output_file_path"]}" não definida; '
+        "o resultado não foi gravado (execução fora da Roberty).",
+        file=sys.stderr,
+    )

roberty_code/run.py

@@ -0,0 +1,36 @@
+import asyncio
+import inspect
+import json
+import sys
+import traceback
+from typing import Any, Callable
+
+from .context import is_roberty
+from .output import output
+
+
+def run(handler: Callable[[Any], Any], exit_on_complete: bool = True) -> Any:
+    """
+    Atalho opcional: executa `handler(roberty)`, grava o retorno como resultado e encerra
+    com exit code 0/1. Fora da Roberty imprime o resultado no stdout. Aceita `async def`.
+    """
+    import roberty_code
+
+    try:
+        result = handler(roberty_code)
+        if inspect.isawaitable(result):
+            result = asyncio.run(result)
+        if result is not None:
+            output(result)
+            if not is_roberty():
+                print(json.dumps(result, indent=2, ensure_ascii=False))
+        if exit_on_complete:
+            sys.exit(0)
+        return result
+    except SystemExit:
+        raise
+    except BaseException:
+        traceback.print_exc()
+        if exit_on_complete:
+            sys.exit(1)
+        raise

roberty_code-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: roberty-code
+Version: 0.1.0
+Summary: SDK oficial para Code Projects da Roberty: leia argumentos, escreva o resultado e descubra o gatilho da execução.
+Project-URL: Homepage, https://github.com/robertyautomation/code-sdk/tree/main/packages/python#readme
+Project-URL: Repository, https://github.com/robertyautomation/code-sdk
+Project-URL: Issues, https://github.com/robertyautomation/code-sdk/issues
+Project-URL: Documentation, https://github.com/robertyautomation/code/blob/main/roberty-code-project-guide.md
+Author: Roberty Automation
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,code-project,roberty,rpa,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# roberty-code
+
+SDK oficial para **Code Projects** da [Roberty](https://roberty.app) em Python. Leia argumentos, escreva o resultado e descubra o gatilho da execução sem lidar com variáveis de ambiente.
+
+```bash
+pip install roberty-code
+```
+
+Python ≥ 3.9. Sem dependências. Tipado.
+
+## Uso
+
+```python
+from datetime import datetime, timezone
+import roberty_code as roberty
+
+print(f"Iniciando ({roberty.environment}, gatilho: {roberty.trigger})")
+
+cpf = roberty.input("cpf")   # um argumento
+args = roberty.inputs()      # todos os argumentos (ou None)
+
+# ... lógica do robô ...
+
+roberty.output({"status": "ok", "processedAt": datetime.now(timezone.utc).isoformat()})
+```
+
+Fora da Roberty o mesmo código roda: `inputs()` devolve `None`, `output()` avisa uma vez e devolve `False`.
+
+## API
+
+| Membro | Retorno | Descrição |
+| --- | --- | --- |
+| `roberty.trigger` | `str \| None` | `manual`, `schedule`, `webhook` ou `evaluation` |
+| `roberty.environment` | `str \| None` | `production` ou `preview` |
+| `roberty.is_roberty` | `bool` | `True` quando roda na Roberty |
+| `roberty.inputs()` | `Any \| None` | Todos os argumentos (`webhook`/`evaluation`) |
+| `roberty.input(name, default=None)` | `Any` | Um argumento específico |
+| `roberty.output(value)` | `bool` | Grava o resultado (JSON) lido pela plataforma |
+| `roberty.exception()` | `ExceptionDetails \| None` | `{"message", "stack", "exitCode"}` dentro do `exceptionHandler` |
+| `roberty.run(handler, exit_on_complete=True)` | `Any` | **Opcional**: executa `handler(roberty)`, grava o retorno e encerra com exit code `0`/`1`. Aceita `async def` |
+| `roberty.ENV_VARS` | `dict` | Nomes das variáveis `roberty-*` |
+
+Erros: `RobertyArgsError` (arquivo de argumentos com JSON inválido) e `RobertyOutputError` (valor não serializável; converta `datetime` com `.isoformat()`).
+
+### `exceptionHandler`
+
+```python
+# on_error.py — declarado em roberty.json como "exceptionHandler": "on_error.py"
+import roberty_code as roberty
+
+error = roberty.exception()
+print(f"Robô falhou (exit code {error['exitCode']}): {error['message']}")
+```
+
+### Atalho `run`
+
+```python
+roberty.run(lambda r: {"status": "ok", "cpf": r.input("cpf")})
+```
+
+Encerra o processo ao terminar; passe `exit_on_complete=False` para embutir em testes.
+
+## Documentação
+
+[Guia de Code Projects](https://github.com/robertyautomation/code/blob/main/roberty-code-project-guide.md): contrato de execução, `roberty.json`, gatilhos e webhook.
+
+## Licença
+
+MIT. Copyright © Roberty Automation. Todos os direitos reservados.

roberty_code-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+roberty_code/__init__.py,sha256=UR05kr3qyLnU4pU1EkSM4QrF8gioQAmVYfIJ_Wj9tXQ,1200
+roberty_code/_args_file.py,sha256=e7Eh3IlYyJyFLccVS_4AsflJJcCsxXz9PycTXsMLESo,682
+roberty_code/_env.py,sha256=-GmFtPw3G4A_DrSV0FbkslJM1QGC8iACnBb2XJEN1n8,255
+roberty_code/context.py,sha256=xDyIcCYp9YWn09Gf1Fmhz7qIBnpDLUZX6asXm-HNF1o,513
+roberty_code/errors.py,sha256=rM8uu29fu16WuaqrWi0WLA3JWJLnD2bVYLDeFh2IYl4,590
+roberty_code/exception.py,sha256=LZHF-CYSq4B28STRfphWoCX5r8Dj2xxZT5p1hClg7yM,613
+roberty_code/inputs.py,sha256=5IUWLHAx7v5kiTdOujqOysnNq2CQnAUpHBAPzMsseFc,701
+roberty_code/output.py,sha256=c4Hd6c-fjcHSfwnN-zqLE5rSLivn0mqGabaOcWlCxQ8,1354
+roberty_code/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+roberty_code/run.py,sha256=U4TQdXdahwq7RXlBcFb6muSunKWrxMon8T02JSu_vJQ,991
+roberty_code-0.1.0.dist-info/METADATA,sha256=LefAiPYdwoadDjuvpK1HJVDP11SJz3b74UR1581jA44,3852
+roberty_code-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+roberty_code-0.1.0.dist-info/licenses/LICENSE,sha256=ut1mZ0GFLRXhMBelw08WVhY3Ww6bZLVV5QmJZRNZdNA,1075
+roberty_code-0.1.0.dist-info/RECORD,,

roberty_code-0.1.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

roberty_code-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roberty Automation
+
+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.