diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 120d183..996b999 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,12 +1,14 @@ name: CI on: push: - branches-ignore: - - 'generated' - - 'codegen/**' - - 'integrated/**' - - 'stl-preview-head/**' - - 'stl-preview-base/**' + branches: + - '**' + - '!integrated/**' + - '!stl-preview-head/**' + - '!stl-preview-base/**' + - '!generated' + - '!codegen/**' + - 'codegen/stl/**' pull_request: branches-ignore: - 'stl-preview-head/**' @@ -17,7 +19,7 @@ jobs: timeout-minutes: 10 name: lint runs-on: ${{ github.repository == 'stainless-sdks/brapi-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} - if: github.event_name == 'push' || github.event.pull_request.head.repo.fork + if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata') steps: - uses: actions/checkout@v6 @@ -36,7 +38,7 @@ jobs: run: ./scripts/lint build: - if: github.event_name == 'push' || github.event.pull_request.head.repo.fork + if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata') timeout-minutes: 10 name: build permissions: @@ -61,14 +63,18 @@ jobs: run: rye build - name: Get GitHub OIDC Token - if: github.repository == 'stainless-sdks/brapi-python' + if: |- + github.repository == 'stainless-sdks/brapi-python' && + !startsWith(github.ref, 'refs/heads/stl/') id: github-oidc uses: actions/github-script@v8 with: script: core.setOutput('github_token', await core.getIDToken()); - name: Upload tarball - if: github.repository == 'stainless-sdks/brapi-python' + if: |- + github.repository == 'stainless-sdks/brapi-python' && + !startsWith(github.ref, 'refs/heads/stl/') env: URL: https://pkg.stainless.com/s AUTH: ${{ steps.github-oidc.outputs.github_token }} diff --git a/.gitignore b/.gitignore index 95ceb18..3824f4c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ .prism.log +.stdy.log _dev __pycache__ diff --git a/.release-please-manifest.json b/.release-please-manifest.json index d0ab664..2a8f4ff 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "1.2.0" + ".": "1.3.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 7d05cc5..d99d5e9 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 11 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/alisson%2Fbrapi-76a60a630b8eaac37bdec27ffec5cbdf6640fb884186adb08211f1b81832c075.yml -openapi_spec_hash: 51fab4b9fd59ce7421f3fdf03644c987 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/alisson/brapi-e435f4c22e29023c8aad36810a131a9c61deb632426a335d47b4efd3acd33c34.yml +openapi_spec_hash: e7c3e281560ced3c46577c08902723cc config_hash: 6f10a67950f65bf850612b59838ad03b diff --git a/CHANGELOG.md b/CHANGELOG.md index 108abc9..d181849 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,31 @@ # Changelog +## 1.3.0 (2026-05-01) + +Full Changelog: [v1.2.0...v1.3.0](https://github.com/brapi-dev/brapi-python/compare/v1.2.0...v1.3.0) + +### Features + +* **api:** api update ([3cd15f0](https://github.com/brapi-dev/brapi-python/commit/3cd15f03d4ef87c43d54a307b5de78cb1668d5fd)) + + +### Chores + +* format all `api.md` files ([691c9c6](https://github.com/brapi-dev/brapi-python/commit/691c9c699beb5779f2593de827024d861963eb73)) +* **internal:** add request options to SSE classes ([c83d52b](https://github.com/brapi-dev/brapi-python/commit/c83d52b1acbd6d9f062aa08aea4633d2ff465ab3)) +* **internal:** bump dependencies ([2afb698](https://github.com/brapi-dev/brapi-python/commit/2afb69816a7f44ee93344c61f94eb86f4c340e9f)) +* **internal:** codegen related update ([1cd1130](https://github.com/brapi-dev/brapi-python/commit/1cd11301a9c48f7e87080f3c0fed1b7ffe65d24e)) +* **internal:** codegen related update ([ca33256](https://github.com/brapi-dev/brapi-python/commit/ca33256ebbce63bc4d1704fed00dfec12fcaee3e)) +* **internal:** codegen related update ([c544f50](https://github.com/brapi-dev/brapi-python/commit/c544f50c8fd0ffe00e9736da46380290f355ead6)) +* **internal:** codegen related update ([6692c9b](https://github.com/brapi-dev/brapi-python/commit/6692c9b20d96d03d072e1db6b56bbcdfe1d852a5)) +* **internal:** codegen related update ([b344fe8](https://github.com/brapi-dev/brapi-python/commit/b344fe8ef180aa53bcba7cae0ab1736031f79941)) +* **internal:** codegen related update ([c48bfd7](https://github.com/brapi-dev/brapi-python/commit/c48bfd77ef22184d9befd319f68a4653e68f03b2)) +* **internal:** fix lint error on Python 3.14 ([8f891ca](https://github.com/brapi-dev/brapi-python/commit/8f891ca4cd532ff0b5bc2ea4748868189d1ac5bf)) +* **internal:** make `test_proxy_environment_variables` more resilient ([a298056](https://github.com/brapi-dev/brapi-python/commit/a298056128baf138f8493c80d34ecc8d67af02fa)) +* **internal:** make `test_proxy_environment_variables` more resilient to env ([a2e60c5](https://github.com/brapi-dev/brapi-python/commit/a2e60c5bb3762cf3de9e7bb7d54a3e6b91a77fb4)) +* **internal:** remove mock server code ([02c10f5](https://github.com/brapi-dev/brapi-python/commit/02c10f56762ea1456bc03934ebddd6c6f78fef81)) +* update mock server docs ([4b7594f](https://github.com/brapi-dev/brapi-python/commit/4b7594fc083f530ddddeaa052a641efaccaf8d6b)) + ## 1.2.0 (2026-01-30) Full Changelog: [v1.1.0...v1.2.0](https://github.com/brapi-dev/brapi-python/compare/v1.1.0...v1.2.0) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5068a3b..9d51ff5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,13 +85,6 @@ $ pip install ./path-to-wheel-file.whl ## Running tests -Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests. - -```sh -# you will need npm installed -$ npx prism mock path/to/your/openapi.yml -``` - ```sh $ ./scripts/test ``` diff --git a/README.md b/README.md index 0c5bf22..8a38d09 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,10 @@ pip install brapi The full API of this library can be found in [api.md](api.md). ```python -import os from brapi import Brapi client = Brapi( - api_key=os.environ.get("BRAPI_API_KEY"), # This is the default and can be omitted + api_key="My API Key", # defaults to "production". environment="environment_1", ) @@ -40,22 +39,16 @@ quote = client.quote.retrieve( print(quote.requested_at) ``` -While you can provide an `api_key` keyword argument, -we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/) -to add `BRAPI_API_KEY="My API Key"` to your `.env` file -so that your API Key is not stored in source control. - ## Async usage Simply import `AsyncBrapi` instead of `Brapi` and use `await` with each API call: ```python -import os import asyncio from brapi import AsyncBrapi client = AsyncBrapi( - api_key=os.environ.get("BRAPI_API_KEY"), # This is the default and can be omitted + api_key="My API Key", # defaults to "production". environment="environment_1", ) @@ -87,7 +80,6 @@ pip install brapi[aiohttp] Then you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`: ```python -import os import asyncio from brapi import DefaultAioHttpClient from brapi import AsyncBrapi @@ -95,7 +87,7 @@ from brapi import AsyncBrapi async def main() -> None: async with AsyncBrapi( - api_key=os.environ.get("BRAPI_API_KEY"), # This is the default and can be omitted + api_key="My API Key", http_client=DefaultAioHttpClient(), ) as client: quote = await client.quote.retrieve( @@ -129,7 +121,9 @@ All errors inherit from `brapi.APIError`. import brapi from brapi import Brapi -client = Brapi() +client = Brapi( + api_key="My API Key", +) try: client.quote.retrieve( @@ -172,6 +166,7 @@ from brapi import Brapi # Configure the default for all requests: client = Brapi( + api_key="My API Key", # default is 2 max_retries=0, ) @@ -192,12 +187,14 @@ from brapi import Brapi # Configure the default for all requests: client = Brapi( + api_key="My API Key", # 20 seconds (default is 1 minute) timeout=20.0, ) # More granular control: client = Brapi( + api_key="My API Key", timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), ) @@ -244,7 +241,9 @@ The "raw" Response object can be accessed by prefixing `.with_raw_response.` to ```py from brapi import Brapi -client = Brapi() +client = Brapi( + api_key="My API Key", +) response = client.quote.with_raw_response.retrieve( tickers="REPLACE_ME", ) @@ -323,6 +322,7 @@ import httpx from brapi import Brapi, DefaultHttpxClient client = Brapi( + api_key="My API Key", # Or use the `BRAPI_BASE_URL` env var base_url="http://my.test.server.example.com:8083", http_client=DefaultHttpxClient( @@ -345,7 +345,9 @@ By default the library closes underlying HTTP connections whenever the client is ```py from brapi import Brapi -with Brapi() as client: +with Brapi( + api_key="My API Key", +) as client: # make requests here ... diff --git a/api.md b/api.md index 5d2bfbf..fd9c66f 100644 --- a/api.md +++ b/api.md @@ -5,11 +5,7 @@ Types: ```python from brapi.types import ( BalanceSheetEntry, - CashflowEntry, - DefaultKeyStatisticsEntry, FinancialDataEntry, - IncomeStatementEntry, - ValueAddedEntry, QuoteRetrieveResponse, QuoteListResponse, ) @@ -71,7 +67,7 @@ from brapi.types.v2 import InflationRetrieveResponse, InflationListAvailableResp Methods: - client.v2.inflation.retrieve(\*\*params) -> InflationRetrieveResponse -- client.v2.inflation.list_available(\*\*params) -> InflationListAvailableResponse +- client.v2.inflation.list_available() -> InflationListAvailableResponse ## PrimeRate @@ -84,4 +80,4 @@ from brapi.types.v2 import PrimeRateRetrieveResponse, PrimeRateListAvailableResp Methods: - client.v2.prime_rate.retrieve(\*\*params) -> PrimeRateRetrieveResponse -- client.v2.prime_rate.list_available(\*\*params) -> PrimeRateListAvailableResponse +- client.v2.prime_rate.list_available() -> PrimeRateListAvailableResponse diff --git a/pyproject.toml b/pyproject.toml index ecae5b3..f13a33e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "brapi" -version = "1.2.0" +version = "1.3.0" description = "The official Python library for the brapi API" dynamic = ["readme"] license = "Apache-2.0" @@ -11,7 +11,7 @@ authors = [ dependencies = [ "httpx>=0.23.0, <1", "pydantic>=1.9.0, <3", - "typing-extensions>=4.10, <5", + "typing-extensions>=4.14, <5", "anyio>=3.5.0, <5", "distro>=1.7.0, <2", "sniffio", @@ -69,7 +69,7 @@ format = { chain = [ # run formatting again to fix any inconsistencies when imports are stripped "format:ruff", ]} -"format:docs" = "python scripts/utils/ruffen-docs.py README.md api.md" +"format:docs" = "bash -c 'python scripts/utils/ruffen-docs.py README.md $(find . -type f -name api.md)'" "format:ruff" = "ruff format" "lint" = { chain = [ @@ -168,7 +168,7 @@ show_error_codes = true # # We also exclude our `tests` as mypy doesn't always infer # types correctly and Pyright will still catch any type errors. -exclude = ['src/brapi/_files.py', '_dev/.*.py', 'tests/.*'] +exclude = ["src/brapi/_files.py", "_dev/.*.py", "tests/.*"] strict_equality = true implicit_reexport = true diff --git a/requirements-dev.lock b/requirements-dev.lock index 659c238..3581988 100644 --- a/requirements-dev.lock +++ b/requirements-dev.lock @@ -12,14 +12,14 @@ -e file:. aiohappyeyeballs==2.6.1 # via aiohttp -aiohttp==3.13.2 +aiohttp==3.13.3 # via brapi # via httpx-aiohttp aiosignal==1.4.0 # via aiohttp annotated-types==0.7.0 # via pydantic -anyio==4.12.0 +anyio==4.12.1 # via brapi # via httpx argcomplete==3.6.3 @@ -31,7 +31,7 @@ attrs==25.4.0 # via nox backports-asyncio-runner==1.2.0 # via pytest-asyncio -certifi==2025.11.12 +certifi==2026.1.4 # via httpcore # via httpx colorlog==6.10.1 @@ -61,7 +61,7 @@ httpx==0.28.1 # via brapi # via httpx-aiohttp # via respx -httpx-aiohttp==0.1.9 +httpx-aiohttp==0.1.12 # via brapi humanize==4.13.0 # via nox @@ -69,7 +69,7 @@ idna==3.11 # via anyio # via httpx # via yarl -importlib-metadata==8.7.0 +importlib-metadata==8.7.1 iniconfig==2.1.0 # via pytest markdown-it-py==3.0.0 @@ -82,14 +82,14 @@ multidict==6.7.0 mypy==1.17.0 mypy-extensions==1.1.0 # via mypy -nodeenv==1.9.1 +nodeenv==1.10.0 # via pyright nox==2025.11.12 packaging==25.0 # via dependency-groups # via nox # via pytest -pathspec==0.12.1 +pathspec==1.0.3 # via mypy platformdirs==4.4.0 # via virtualenv @@ -115,13 +115,13 @@ python-dateutil==2.9.0.post0 # via time-machine respx==0.22.0 rich==14.2.0 -ruff==0.14.7 +ruff==0.14.13 six==1.17.0 # via python-dateutil sniffio==1.3.1 # via brapi time-machine==2.19.0 -tomli==2.3.0 +tomli==2.4.0 # via dependency-groups # via mypy # via nox @@ -141,7 +141,7 @@ typing-extensions==4.15.0 # via virtualenv typing-inspection==0.4.2 # via pydantic -virtualenv==20.35.4 +virtualenv==20.36.1 # via nox yarl==1.22.0 # via aiohttp diff --git a/requirements.lock b/requirements.lock index f030e74..b885522 100644 --- a/requirements.lock +++ b/requirements.lock @@ -12,21 +12,21 @@ -e file:. aiohappyeyeballs==2.6.1 # via aiohttp -aiohttp==3.13.2 +aiohttp==3.13.3 # via brapi # via httpx-aiohttp aiosignal==1.4.0 # via aiohttp annotated-types==0.7.0 # via pydantic -anyio==4.12.0 +anyio==4.12.1 # via brapi # via httpx async-timeout==5.0.1 # via aiohttp attrs==25.4.0 # via aiohttp -certifi==2025.11.12 +certifi==2026.1.4 # via httpcore # via httpx distro==1.9.0 @@ -43,7 +43,7 @@ httpcore==1.0.9 httpx==0.28.1 # via brapi # via httpx-aiohttp -httpx-aiohttp==0.1.9 +httpx-aiohttp==0.1.12 # via brapi idna==3.11 # via anyio diff --git a/scripts/bootstrap b/scripts/bootstrap index b430fee..fe8451e 100755 --- a/scripts/bootstrap +++ b/scripts/bootstrap @@ -4,7 +4,7 @@ set -e cd "$(dirname "$0")/.." -if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ] && [ -t 0 ]; then +if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "${SKIP_BREW:-}" != "1" ] && [ -t 0 ]; then brew bundle check >/dev/null 2>&1 || { echo -n "==> Install Homebrew dependencies? (y/N): " read -r response diff --git a/scripts/mock b/scripts/mock deleted file mode 100755 index 0b28f6e..0000000 --- a/scripts/mock +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/env bash - -set -e - -cd "$(dirname "$0")/.." - -if [[ -n "$1" && "$1" != '--'* ]]; then - URL="$1" - shift -else - URL="$(grep 'openapi_spec_url' .stats.yml | cut -d' ' -f2)" -fi - -# Check if the URL is empty -if [ -z "$URL" ]; then - echo "Error: No OpenAPI spec path/url provided or found in .stats.yml" - exit 1 -fi - -echo "==> Starting mock server with URL ${URL}" - -# Run prism mock on the given spec -if [ "$1" == "--daemon" ]; then - npm exec --package=@stainless-api/prism-cli@5.15.0 -- prism mock "$URL" &> .prism.log & - - # Wait for server to come online - echo -n "Waiting for server" - while ! grep -q "✖ fatal\|Prism is listening" ".prism.log" ; do - echo -n "." - sleep 0.1 - done - - if grep -q "✖ fatal" ".prism.log"; then - cat .prism.log - exit 1 - fi - - echo -else - npm exec --package=@stainless-api/prism-cli@5.15.0 -- prism mock "$URL" -fi diff --git a/scripts/test b/scripts/test index dbeda2d..39729d0 100755 --- a/scripts/test +++ b/scripts/test @@ -4,53 +4,7 @@ set -e cd "$(dirname "$0")/.." -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[0;33m' -NC='\033[0m' # No Color -function prism_is_running() { - curl --silent "http://localhost:4010" >/dev/null 2>&1 -} - -kill_server_on_port() { - pids=$(lsof -t -i tcp:"$1" || echo "") - if [ "$pids" != "" ]; then - kill "$pids" - echo "Stopped $pids." - fi -} - -function is_overriding_api_base_url() { - [ -n "$TEST_API_BASE_URL" ] -} - -if ! is_overriding_api_base_url && ! prism_is_running ; then - # When we exit this script, make sure to kill the background mock server process - trap 'kill_server_on_port 4010' EXIT - - # Start the dev server - ./scripts/mock --daemon -fi - -if is_overriding_api_base_url ; then - echo -e "${GREEN}✔ Running tests against ${TEST_API_BASE_URL}${NC}" - echo -elif ! prism_is_running ; then - echo -e "${RED}ERROR:${NC} The test suite will not run without a mock Prism server" - echo -e "running against your OpenAPI spec." - echo - echo -e "To run the server, pass in the path or url of your OpenAPI" - echo -e "spec to the prism command:" - echo - echo -e " \$ ${YELLOW}npm exec --package=@stainless-api/prism-cli@5.15.0 -- prism mock path/to/your.openapi.yml${NC}" - echo - - exit 1 -else - echo -e "${GREEN}✔ Mock prism server is running with your OpenAPI spec${NC}" - echo -fi export DEFER_PYDANTIC_BUILD=false diff --git a/src/brapi/_base_client.py b/src/brapi/_base_client.py index 9adac9a..512f6b9 100644 --- a/src/brapi/_base_client.py +++ b/src/brapi/_base_client.py @@ -540,6 +540,10 @@ def _build_request( files = cast(HttpxRequestFiles, ForceMultipartDict()) prepared_url = self._prepare_url(options.url) + # preserve hard-coded query params from the url + if params and prepared_url.query: + params = {**dict(prepared_url.params.items()), **params} + prepared_url = prepared_url.copy_with(raw_path=prepared_url.raw_path.split(b"?", 1)[0]) if "_" in prepared_url.host: # work around https://github.com/encode/httpx/discussions/2880 kwargs["extensions"] = {"sni_hostname": prepared_url.host.replace("_", "-")} diff --git a/src/brapi/_client.py b/src/brapi/_client.py index 80b62ff..e9950d3 100644 --- a/src/brapi/_client.py +++ b/src/brapi/_client.py @@ -19,7 +19,11 @@ RequestOptions, not_given, ) -from ._utils import is_given, get_async_library +from ._utils import ( + is_given, + is_mapping_t, + get_async_library, +) from ._compat import cached_property from ._version import __version__ from ._streaming import Stream as Stream, AsyncStream as AsyncStream @@ -122,6 +126,15 @@ def __init__( except KeyError as exc: raise ValueError(f"Unknown environment: {environment}") from exc + custom_headers_env = os.environ.get("BRAPI_CUSTOM_HEADERS") + if custom_headers_env is not None: + parsed: dict[str, str] = {} + for line in custom_headers_env.split("\n"): + colon = line.find(":") + if colon >= 0: + parsed[line[:colon].strip()] = line[colon + 1 :].strip() + default_headers = {**parsed, **(default_headers if is_mapping_t(default_headers) else {})} + super().__init__( version=__version__, base_url=base_url, @@ -135,12 +148,19 @@ def __init__( @cached_property def quote(self) -> QuoteResource: + """Consulte informações detalhadas sobre ações, BDRs, ETFs e índices da B3. + + Obtenha preços em tempo real, dados fundamentalistas, históricos e dividendos. + """ from .resources.quote import QuoteResource return QuoteResource(self) @cached_property def available(self) -> AvailableResource: + """ + Ferramentas auxiliares para descobrir ativos disponíveis e verificar a saúde da API. + """ from .resources.available import AvailableResource return AvailableResource(self) @@ -164,12 +184,6 @@ def with_streaming_response(self) -> BrapiWithStreamedResponse: def qs(self) -> Querystring: return Querystring(array_format="comma") - @property - @override - def auth_headers(self) -> dict[str, str]: - api_key = self.api_key - return {"Authorization": f"Bearer {api_key}"} - @property @override def default_headers(self) -> dict[str, str | Omit]: @@ -334,6 +348,15 @@ def __init__( except KeyError as exc: raise ValueError(f"Unknown environment: {environment}") from exc + custom_headers_env = os.environ.get("BRAPI_CUSTOM_HEADERS") + if custom_headers_env is not None: + parsed: dict[str, str] = {} + for line in custom_headers_env.split("\n"): + colon = line.find(":") + if colon >= 0: + parsed[line[:colon].strip()] = line[colon + 1 :].strip() + default_headers = {**parsed, **(default_headers if is_mapping_t(default_headers) else {})} + super().__init__( version=__version__, base_url=base_url, @@ -347,12 +370,19 @@ def __init__( @cached_property def quote(self) -> AsyncQuoteResource: + """Consulte informações detalhadas sobre ações, BDRs, ETFs e índices da B3. + + Obtenha preços em tempo real, dados fundamentalistas, históricos e dividendos. + """ from .resources.quote import AsyncQuoteResource return AsyncQuoteResource(self) @cached_property def available(self) -> AsyncAvailableResource: + """ + Ferramentas auxiliares para descobrir ativos disponíveis e verificar a saúde da API. + """ from .resources.available import AsyncAvailableResource return AsyncAvailableResource(self) @@ -376,12 +406,6 @@ def with_streaming_response(self) -> AsyncBrapiWithStreamedResponse: def qs(self) -> Querystring: return Querystring(array_format="comma") - @property - @override - def auth_headers(self) -> dict[str, str]: - api_key = self.api_key - return {"Authorization": f"Bearer {api_key}"} - @property @override def default_headers(self) -> dict[str, str | Omit]: @@ -486,12 +510,19 @@ def __init__(self, client: Brapi) -> None: @cached_property def quote(self) -> quote.QuoteResourceWithRawResponse: + """Consulte informações detalhadas sobre ações, BDRs, ETFs e índices da B3. + + Obtenha preços em tempo real, dados fundamentalistas, históricos e dividendos. + """ from .resources.quote import QuoteResourceWithRawResponse return QuoteResourceWithRawResponse(self._client.quote) @cached_property def available(self) -> available.AvailableResourceWithRawResponse: + """ + Ferramentas auxiliares para descobrir ativos disponíveis e verificar a saúde da API. + """ from .resources.available import AvailableResourceWithRawResponse return AvailableResourceWithRawResponse(self._client.available) @@ -511,12 +542,19 @@ def __init__(self, client: AsyncBrapi) -> None: @cached_property def quote(self) -> quote.AsyncQuoteResourceWithRawResponse: + """Consulte informações detalhadas sobre ações, BDRs, ETFs e índices da B3. + + Obtenha preços em tempo real, dados fundamentalistas, históricos e dividendos. + """ from .resources.quote import AsyncQuoteResourceWithRawResponse return AsyncQuoteResourceWithRawResponse(self._client.quote) @cached_property def available(self) -> available.AsyncAvailableResourceWithRawResponse: + """ + Ferramentas auxiliares para descobrir ativos disponíveis e verificar a saúde da API. + """ from .resources.available import AsyncAvailableResourceWithRawResponse return AsyncAvailableResourceWithRawResponse(self._client.available) @@ -536,12 +574,19 @@ def __init__(self, client: Brapi) -> None: @cached_property def quote(self) -> quote.QuoteResourceWithStreamingResponse: + """Consulte informações detalhadas sobre ações, BDRs, ETFs e índices da B3. + + Obtenha preços em tempo real, dados fundamentalistas, históricos e dividendos. + """ from .resources.quote import QuoteResourceWithStreamingResponse return QuoteResourceWithStreamingResponse(self._client.quote) @cached_property def available(self) -> available.AvailableResourceWithStreamingResponse: + """ + Ferramentas auxiliares para descobrir ativos disponíveis e verificar a saúde da API. + """ from .resources.available import AvailableResourceWithStreamingResponse return AvailableResourceWithStreamingResponse(self._client.available) @@ -561,12 +606,19 @@ def __init__(self, client: AsyncBrapi) -> None: @cached_property def quote(self) -> quote.AsyncQuoteResourceWithStreamingResponse: + """Consulte informações detalhadas sobre ações, BDRs, ETFs e índices da B3. + + Obtenha preços em tempo real, dados fundamentalistas, históricos e dividendos. + """ from .resources.quote import AsyncQuoteResourceWithStreamingResponse return AsyncQuoteResourceWithStreamingResponse(self._client.quote) @cached_property def available(self) -> available.AsyncAvailableResourceWithStreamingResponse: + """ + Ferramentas auxiliares para descobrir ativos disponíveis e verificar a saúde da API. + """ from .resources.available import AsyncAvailableResourceWithStreamingResponse return AsyncAvailableResourceWithStreamingResponse(self._client.available) diff --git a/src/brapi/_compat.py b/src/brapi/_compat.py index 786ff42..e6690a4 100644 --- a/src/brapi/_compat.py +++ b/src/brapi/_compat.py @@ -2,7 +2,7 @@ from typing import TYPE_CHECKING, Any, Union, Generic, TypeVar, Callable, cast, overload from datetime import date, datetime -from typing_extensions import Self, Literal +from typing_extensions import Self, Literal, TypedDict import pydantic from pydantic.fields import FieldInfo @@ -131,6 +131,10 @@ def model_json(model: pydantic.BaseModel, *, indent: int | None = None) -> str: return model.model_dump_json(indent=indent) +class _ModelDumpKwargs(TypedDict, total=False): + by_alias: bool + + def model_dump( model: pydantic.BaseModel, *, @@ -142,6 +146,9 @@ def model_dump( by_alias: bool | None = None, ) -> dict[str, Any]: if (not PYDANTIC_V1) or hasattr(model, "model_dump"): + kwargs: _ModelDumpKwargs = {} + if by_alias is not None: + kwargs["by_alias"] = by_alias return model.model_dump( mode=mode, exclude=exclude, @@ -149,7 +156,7 @@ def model_dump( exclude_defaults=exclude_defaults, # warnings are not supported in Pydantic v1 warnings=True if PYDANTIC_V1 else warnings, - by_alias=by_alias, + **kwargs, ) return cast( "dict[str, Any]", diff --git a/src/brapi/_files.py b/src/brapi/_files.py index cc14c14..0fdce17 100644 --- a/src/brapi/_files.py +++ b/src/brapi/_files.py @@ -3,8 +3,8 @@ import io import os import pathlib -from typing import overload -from typing_extensions import TypeGuard +from typing import Sequence, cast, overload +from typing_extensions import TypeVar, TypeGuard import anyio @@ -17,7 +17,9 @@ HttpxFileContent, HttpxRequestFiles, ) -from ._utils import is_tuple_t, is_mapping_t, is_sequence_t +from ._utils import is_list, is_mapping, is_tuple_t, is_mapping_t, is_sequence_t + +_T = TypeVar("_T") def is_base64_file_input(obj: object) -> TypeGuard[Base64FileInput]: @@ -121,3 +123,51 @@ async def async_read_file_content(file: FileContent) -> HttpxFileContent: return await anyio.Path(file).read_bytes() return file + + +def deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]]) -> _T: + """Copy only the containers along the given paths. + + Used to guard against mutation by extract_files without copying the entire structure. + Only dicts and lists that lie on a path are copied; everything else + is returned by reference. + + For example, given paths=[["foo", "files", "file"]] and the structure: + { + "foo": { + "bar": {"baz": {}}, + "files": {"file": } + } + } + The root dict, "foo", and "files" are copied (they lie on the path). + "bar" and "baz" are returned by reference (off the path). + """ + return _deepcopy_with_paths(item, paths, 0) + + +def _deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]], index: int) -> _T: + if not paths: + return item + if is_mapping(item): + key_to_paths: dict[str, list[Sequence[str]]] = {} + for path in paths: + if index < len(path): + key_to_paths.setdefault(path[index], []).append(path) + + # if no path continues through this mapping, it won't be mutated and copying it is redundant + if not key_to_paths: + return item + + result = dict(item) + for key, subpaths in key_to_paths.items(): + if key in result: + result[key] = _deepcopy_with_paths(result[key], subpaths, index + 1) + return cast(_T, result) + if is_list(item): + array_paths = [path for path in paths if index < len(path) and path[index] == ""] + + # if no path expects a list here, nothing will be mutated inside it - return by reference + if not array_paths: + return cast(_T, item) + return cast(_T, [_deepcopy_with_paths(entry, array_paths, index + 1) for entry in item]) + return item diff --git a/src/brapi/_qs.py b/src/brapi/_qs.py index ada6fd3..4127c19 100644 --- a/src/brapi/_qs.py +++ b/src/brapi/_qs.py @@ -2,17 +2,13 @@ from typing import Any, List, Tuple, Union, Mapping, TypeVar from urllib.parse import parse_qs, urlencode -from typing_extensions import Literal, get_args +from typing_extensions import get_args -from ._types import NotGiven, not_given +from ._types import NotGiven, ArrayFormat, NestedFormat, not_given from ._utils import flatten _T = TypeVar("_T") - -ArrayFormat = Literal["comma", "repeat", "indices", "brackets"] -NestedFormat = Literal["dots", "brackets"] - PrimitiveData = Union[str, int, float, bool, None] # this should be Data = Union[PrimitiveData, "List[Data]", "Tuple[Data]", "Mapping[str, Data]"] # https://github.com/microsoft/pyright/issues/3555 @@ -101,7 +97,10 @@ def _stringify_item( items.extend(self._stringify_item(key, item, opts)) return items elif array_format == "indices": - raise NotImplementedError("The array indices format is not supported yet") + items = [] + for i, item in enumerate(value): + items.extend(self._stringify_item(f"{key}[{i}]", item, opts)) + return items elif array_format == "brackets": items = [] key = key + "[]" diff --git a/src/brapi/_response.py b/src/brapi/_response.py index 0f7b71f..b2aad2b 100644 --- a/src/brapi/_response.py +++ b/src/brapi/_response.py @@ -152,6 +152,7 @@ def _parse(self, *, to: type[_T] | None = None) -> R | _T: ), response=self.http_response, client=cast(Any, self._client), + options=self._options, ), ) @@ -162,6 +163,7 @@ def _parse(self, *, to: type[_T] | None = None) -> R | _T: cast_to=extract_stream_chunk_type(self._stream_cls), response=self.http_response, client=cast(Any, self._client), + options=self._options, ), ) @@ -175,6 +177,7 @@ def _parse(self, *, to: type[_T] | None = None) -> R | _T: cast_to=cast_to, response=self.http_response, client=cast(Any, self._client), + options=self._options, ), ) diff --git a/src/brapi/_streaming.py b/src/brapi/_streaming.py index e5f7242..258e79d 100644 --- a/src/brapi/_streaming.py +++ b/src/brapi/_streaming.py @@ -4,7 +4,7 @@ import json import inspect from types import TracebackType -from typing import TYPE_CHECKING, Any, Generic, TypeVar, Iterator, AsyncIterator, cast +from typing import TYPE_CHECKING, Any, Generic, TypeVar, Iterator, Optional, AsyncIterator, cast from typing_extensions import Self, Protocol, TypeGuard, override, get_origin, runtime_checkable import httpx @@ -13,6 +13,7 @@ if TYPE_CHECKING: from ._client import Brapi, AsyncBrapi + from ._models import FinalRequestOptions _T = TypeVar("_T") @@ -22,7 +23,7 @@ class Stream(Generic[_T]): """Provides the core interface to iterate over a synchronous stream response.""" response: httpx.Response - + _options: Optional[FinalRequestOptions] = None _decoder: SSEBytesDecoder def __init__( @@ -31,10 +32,12 @@ def __init__( cast_to: type[_T], response: httpx.Response, client: Brapi, + options: Optional[FinalRequestOptions] = None, ) -> None: self.response = response self._cast_to = cast_to self._client = client + self._options = options self._decoder = client._make_sse_decoder() self._iterator = self.__stream__() @@ -85,7 +88,7 @@ class AsyncStream(Generic[_T]): """Provides the core interface to iterate over an asynchronous stream response.""" response: httpx.Response - + _options: Optional[FinalRequestOptions] = None _decoder: SSEDecoder | SSEBytesDecoder def __init__( @@ -94,10 +97,12 @@ def __init__( cast_to: type[_T], response: httpx.Response, client: AsyncBrapi, + options: Optional[FinalRequestOptions] = None, ) -> None: self.response = response self._cast_to = cast_to self._client = client + self._options = options self._decoder = client._make_sse_decoder() self._iterator = self.__stream__() diff --git a/src/brapi/_types.py b/src/brapi/_types.py index 60c1ea8..1e86c02 100644 --- a/src/brapi/_types.py +++ b/src/brapi/_types.py @@ -47,6 +47,9 @@ ModelT = TypeVar("ModelT", bound=pydantic.BaseModel) _T = TypeVar("_T") +ArrayFormat = Literal["comma", "repeat", "indices", "brackets"] +NestedFormat = Literal["dots", "brackets"] + # Approximates httpx internal ProxiesTypes and RequestFiles types # while adding support for `PathLike` instances diff --git a/src/brapi/_utils/__init__.py b/src/brapi/_utils/__init__.py index dc64e29..1c090e5 100644 --- a/src/brapi/_utils/__init__.py +++ b/src/brapi/_utils/__init__.py @@ -1,3 +1,4 @@ +from ._path import path_template as path_template from ._sync import asyncify as asyncify from ._proxy import LazyProxy as LazyProxy from ._utils import ( @@ -23,7 +24,6 @@ coerce_integer as coerce_integer, file_from_path as file_from_path, strip_not_given as strip_not_given, - deepcopy_minimal as deepcopy_minimal, get_async_library as get_async_library, maybe_coerce_float as maybe_coerce_float, get_required_header as get_required_header, diff --git a/src/brapi/_utils/_compat.py b/src/brapi/_utils/_compat.py index dd70323..2c70b29 100644 --- a/src/brapi/_utils/_compat.py +++ b/src/brapi/_utils/_compat.py @@ -26,7 +26,7 @@ def is_union(tp: Optional[Type[Any]]) -> bool: else: import types - return tp is Union or tp is types.UnionType + return tp is Union or tp is types.UnionType # type: ignore[comparison-overlap] def is_typeddict(tp: Type[Any]) -> bool: diff --git a/src/brapi/_utils/_path.py b/src/brapi/_utils/_path.py new file mode 100644 index 0000000..4d6e1e4 --- /dev/null +++ b/src/brapi/_utils/_path.py @@ -0,0 +1,127 @@ +from __future__ import annotations + +import re +from typing import ( + Any, + Mapping, + Callable, +) +from urllib.parse import quote + +# Matches '.' or '..' where each dot is either literal or percent-encoded (%2e / %2E). +_DOT_SEGMENT_RE = re.compile(r"^(?:\.|%2[eE]){1,2}$") + +_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}") + + +def _quote_path_segment_part(value: str) -> str: + """Percent-encode `value` for use in a URI path segment. + + Considers characters not in `pchar` set from RFC 3986 §3.3 to be unsafe. + https://datatracker.ietf.org/doc/html/rfc3986#section-3.3 + """ + # quote() already treats unreserved characters (letters, digits, and -._~) + # as safe, so we only need to add sub-delims, ':', and '@'. + # Notably, unlike the default `safe` for quote(), / is unsafe and must be quoted. + return quote(value, safe="!$&'()*+,;=:@") + + +def _quote_query_part(value: str) -> str: + """Percent-encode `value` for use in a URI query string. + + Considers &, = and characters not in `query` set from RFC 3986 §3.4 to be unsafe. + https://datatracker.ietf.org/doc/html/rfc3986#section-3.4 + """ + return quote(value, safe="!$'()*+,;:@/?") + + +def _quote_fragment_part(value: str) -> str: + """Percent-encode `value` for use in a URI fragment. + + Considers characters not in `fragment` set from RFC 3986 §3.5 to be unsafe. + https://datatracker.ietf.org/doc/html/rfc3986#section-3.5 + """ + return quote(value, safe="!$&'()*+,;=:@/?") + + +def _interpolate( + template: str, + values: Mapping[str, Any], + quoter: Callable[[str], str], +) -> str: + """Replace {name} placeholders in `template`, quoting each value with `quoter`. + + Placeholder names are looked up in `values`. + + Raises: + KeyError: If a placeholder is not found in `values`. + """ + # re.split with a capturing group returns alternating + # [text, name, text, name, ..., text] elements. + parts = _PLACEHOLDER_RE.split(template) + + for i in range(1, len(parts), 2): + name = parts[i] + if name not in values: + raise KeyError(f"a value for placeholder {{{name}}} was not provided") + val = values[name] + if val is None: + parts[i] = "null" + elif isinstance(val, bool): + parts[i] = "true" if val else "false" + else: + parts[i] = quoter(str(values[name])) + + return "".join(parts) + + +def path_template(template: str, /, **kwargs: Any) -> str: + """Interpolate {name} placeholders in `template` from keyword arguments. + + Args: + template: The template string containing {name} placeholders. + **kwargs: Keyword arguments to interpolate into the template. + + Returns: + The template with placeholders interpolated and percent-encoded. + + Safe characters for percent-encoding are dependent on the URI component. + Placeholders in path and fragment portions are percent-encoded where the `segment` + and `fragment` sets from RFC 3986 respectively are considered safe. + Placeholders in the query portion are percent-encoded where the `query` set from + RFC 3986 §3.3 is considered safe except for = and & characters. + + Raises: + KeyError: If a placeholder is not found in `kwargs`. + ValueError: If resulting path contains /./ or /../ segments (including percent-encoded dot-segments). + """ + # Split the template into path, query, and fragment portions. + fragment_template: str | None = None + query_template: str | None = None + + rest = template + if "#" in rest: + rest, fragment_template = rest.split("#", 1) + if "?" in rest: + rest, query_template = rest.split("?", 1) + path_template = rest + + # Interpolate each portion with the appropriate quoting rules. + path_result = _interpolate(path_template, kwargs, _quote_path_segment_part) + + # Reject dot-segments (. and ..) in the final assembled path. The check + # runs after interpolation so that adjacent placeholders or a mix of static + # text and placeholders that together form a dot-segment are caught. + # Also reject percent-encoded dot-segments to protect against incorrectly + # implemented normalization in servers/proxies. + for segment in path_result.split("/"): + if _DOT_SEGMENT_RE.match(segment): + raise ValueError(f"Constructed path {path_result!r} contains dot-segment {segment!r} which is not allowed") + + result = path_result + if query_template is not None: + result += "?" + _interpolate(query_template, kwargs, _quote_query_part) + if fragment_template is not None: + result += "#" + _interpolate(fragment_template, kwargs, _quote_fragment_part) + + return result diff --git a/src/brapi/_utils/_utils.py b/src/brapi/_utils/_utils.py index eec7f4a..199cd23 100644 --- a/src/brapi/_utils/_utils.py +++ b/src/brapi/_utils/_utils.py @@ -17,11 +17,11 @@ ) from pathlib import Path from datetime import date, datetime -from typing_extensions import TypeGuard +from typing_extensions import TypeGuard, get_args import sniffio -from .._types import Omit, NotGiven, FileTypes, HeadersLike +from .._types import Omit, NotGiven, FileTypes, ArrayFormat, HeadersLike _T = TypeVar("_T") _TupleT = TypeVar("_TupleT", bound=Tuple[object, ...]) @@ -40,25 +40,45 @@ def extract_files( query: Mapping[str, object], *, paths: Sequence[Sequence[str]], + array_format: ArrayFormat = "brackets", ) -> list[tuple[str, FileTypes]]: """Recursively extract files from the given dictionary based on specified paths. A path may look like this ['foo', 'files', '', 'data']. + ``array_format`` controls how ```` segments contribute to the emitted + field name. Supported values: ``"brackets"`` (``foo[]``), ``"repeat"`` and + ``"comma"`` (``foo``), ``"indices"`` (``foo[0]``, ``foo[1]``). + Note: this mutates the given dictionary. """ files: list[tuple[str, FileTypes]] = [] for path in paths: - files.extend(_extract_items(query, path, index=0, flattened_key=None)) + files.extend(_extract_items(query, path, index=0, flattened_key=None, array_format=array_format)) return files +def _array_suffix(array_format: ArrayFormat, array_index: int) -> str: + if array_format == "brackets": + return "[]" + if array_format == "indices": + return f"[{array_index}]" + if array_format == "repeat" or array_format == "comma": + # Both repeat the bare field name for each file part; there is no + # meaningful way to comma-join binary parts. + return "" + raise NotImplementedError( + f"Unknown array_format value: {array_format}, choose from {', '.join(get_args(ArrayFormat))}" + ) + + def _extract_items( obj: object, path: Sequence[str], *, index: int, flattened_key: str | None, + array_format: ArrayFormat, ) -> list[tuple[str, FileTypes]]: try: key = path[index] @@ -75,9 +95,11 @@ def _extract_items( if is_list(obj): files: list[tuple[str, FileTypes]] = [] - for entry in obj: - assert_is_file_content(entry, key=flattened_key + "[]" if flattened_key else "") - files.append((flattened_key + "[]", cast(FileTypes, entry))) + for array_index, entry in enumerate(obj): + suffix = _array_suffix(array_format, array_index) + emitted_key = (flattened_key + suffix) if flattened_key else suffix + assert_is_file_content(entry, key=emitted_key) + files.append((emitted_key, cast(FileTypes, entry))) return files assert_is_file_content(obj, key=flattened_key) @@ -86,8 +108,9 @@ def _extract_items( index += 1 if is_dict(obj): try: - # We are at the last entry in the path so we must remove the field - if (len(path)) == index: + # Remove the field if there are no more dict keys in the path, + # only "" traversal markers or end. + if all(p == "" for p in path[index:]): item = obj.pop(key) else: item = obj[key] @@ -105,6 +128,7 @@ def _extract_items( path, index=index, flattened_key=flattened_key, + array_format=array_format, ) elif is_list(obj): if key != "": @@ -116,9 +140,12 @@ def _extract_items( item, path, index=index, - flattened_key=flattened_key + "[]" if flattened_key is not None else "[]", + flattened_key=( + (flattened_key if flattened_key is not None else "") + _array_suffix(array_format, array_index) + ), + array_format=array_format, ) - for item in obj + for array_index, item in enumerate(obj) ] ) @@ -176,21 +203,6 @@ def is_iterable(obj: object) -> TypeGuard[Iterable[object]]: return isinstance(obj, Iterable) -def deepcopy_minimal(item: _T) -> _T: - """Minimal reimplementation of copy.deepcopy() that will only copy certain object types: - - - mappings, e.g. `dict` - - list - - This is done for performance reasons. - """ - if is_mapping(item): - return cast(_T, {k: deepcopy_minimal(v) for k, v in item.items()}) - if is_list(item): - return cast(_T, [deepcopy_minimal(entry) for entry in item]) - return item - - # copied from https://github.com/Rapptz/RoboDanny def human_join(seq: Sequence[str], *, delim: str = ", ", final: str = "or") -> str: size = len(seq) diff --git a/src/brapi/_version.py b/src/brapi/_version.py index 165bd5b..4da6408 100644 --- a/src/brapi/_version.py +++ b/src/brapi/_version.py @@ -1,4 +1,4 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. __title__ = "brapi" -__version__ = "1.2.0" # x-release-please-version +__version__ = "1.3.0" # x-release-please-version diff --git a/src/brapi/resources/available.py b/src/brapi/resources/available.py index 26e04de..0ef1f33 100644 --- a/src/brapi/resources/available.py +++ b/src/brapi/resources/available.py @@ -22,6 +22,10 @@ class AvailableResource(SyncAPIResource): + """ + Ferramentas auxiliares para descobrir ativos disponíveis e verificar a saúde da API. + """ + @cached_property def with_raw_response(self) -> AvailableResourceWithRawResponse: """ @@ -44,7 +48,6 @@ def with_streaming_response(self) -> AvailableResourceWithStreamingResponse: def list( self, *, - token: str | Omit = omit, search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. @@ -54,58 +57,65 @@ def list( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> AvailableListResponse: """ - Obtenha uma lista completa de todos os tickers (identificadores) de ativos - financeiros (ações, FIIs, BDRs, ETFs, índices) que a API Brapi tem dados - disponíveis para consulta no endpoint `/api/quote/{tickers}`. - - ### Funcionalidade: + Retorna a lista completa de **ações e índices** disponíveis para consulta na API + brapi. - - Retorna arrays separados para `indexes` (índices) e `stocks` (outros ativos). - - Pode ser filtrado usando o parâmetro `search` para encontrar tickers - específicos. + ### Funcionalidades - ### Autenticação: + - **Ações da B3:** Todas as ações, FIIs, BDRs e ETFs negociados na bolsa + brasileira + - **Índices:** Principais índices do mercado brasileiro (Ibovespa, IBrX, IFIX, + etc.) + - **Filtro por Nome:** Use `search` para filtrar por código ou nome do ativo - Requer token de autenticação via `token` (query) ou `Authorization` (header). + ### Características - ### Exemplo de Requisição: + - **Sem Autenticação:** Este endpoint é **público** e não requer token + - **Cache:** Dados cacheados por 15 minutos + - **Atualização automática:** Conforme novos ativos são listados na B3 - **Listar todos os tickers disponíveis:** + ### Exemplos de Uso ```bash - curl -X GET "https://brapi.dev/api/available?token=SEU_TOKEN" - ``` + # Listar todos os ativos + curl "https://brapi.dev/api/available" - **Buscar tickers que contenham 'BBDC':** + # Buscar por código de ticker + curl "https://brapi.dev/api/available?search=PETR" - ```bash - curl -X GET "https://brapi.dev/api/available?search=BBDC&token=SEU_TOKEN" + # Buscar por nome da empresa + curl "https://brapi.dev/api/available?search=banco" ``` - ### Resposta: + ### Índices Disponíveis - A resposta é um objeto JSON com duas chaves: + - `^BVSP` — Ibovespa (Índice Bovespa) + - `^IBX50` — IBrX 50 + - `^IBX100` — IBrX 100 + - `^IDIV` — Índice Dividendos + - `^SMLL` — Índice Small Cap + - `^IFIX` — Índice de Fundos Imobiliários + - `^IFNC` — Índice Financeiro + - `^ICON` — Índice de Consumo + - `^IEEX` — Índice de Energia Elétrica + - `^IMOB` — Índice Imobiliário - - `indexes`: Array de strings contendo os tickers dos índices disponíveis (ex: - `["^BVSP", "^IFIX"]`). - - `stocks`: Array de strings contendo os tickers das ações, FIIs, BDRs e ETFs - disponíveis (ex: `["PETR4", "VALE3", "ITSA4", "MXRF11"]`). + ### Campos da Resposta - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + - `stocks` — Array com códigos das ações (ex: ["PETR4", "VALE3", "ITUB4", ...]) + - `indexes` — Array com códigos dos índices (ex: ["^BVSP", "^IFIX", ...]) + + ### Como Usar - **Formas de Envio:** + Use os códigos retornados como parâmetro no endpoint `/api/quote/{tickers}` para + obter cotações detalhadas. - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + **Fonte:** B3 (Bolsa de Valores do Brasil) - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + **Plano Mínimo:** Gratuito **Autenticação:** Não necessária (Público) - search: **Opcional.** Termo para filtrar a lista de tickers (correspondência parcial, - case-insensitive). Se omitido, retorna todos os tickers. + Args: + search: Filtrar ações e índices por nome ou código extra_headers: Send extra headers @@ -122,19 +132,17 @@ def list( extra_query=extra_query, extra_body=extra_body, timeout=timeout, - query=maybe_transform( - { - "token": token, - "search": search, - }, - available_list_params.AvailableListParams, - ), + query=maybe_transform({"search": search}, available_list_params.AvailableListParams), ), cast_to=AvailableListResponse, ) class AsyncAvailableResource(AsyncAPIResource): + """ + Ferramentas auxiliares para descobrir ativos disponíveis e verificar a saúde da API. + """ + @cached_property def with_raw_response(self) -> AsyncAvailableResourceWithRawResponse: """ @@ -157,7 +165,6 @@ def with_streaming_response(self) -> AsyncAvailableResourceWithStreamingResponse async def list( self, *, - token: str | Omit = omit, search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. @@ -167,58 +174,65 @@ async def list( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> AvailableListResponse: """ - Obtenha uma lista completa de todos os tickers (identificadores) de ativos - financeiros (ações, FIIs, BDRs, ETFs, índices) que a API Brapi tem dados - disponíveis para consulta no endpoint `/api/quote/{tickers}`. - - ### Funcionalidade: + Retorna a lista completa de **ações e índices** disponíveis para consulta na API + brapi. - - Retorna arrays separados para `indexes` (índices) e `stocks` (outros ativos). - - Pode ser filtrado usando o parâmetro `search` para encontrar tickers - específicos. + ### Funcionalidades - ### Autenticação: + - **Ações da B3:** Todas as ações, FIIs, BDRs e ETFs negociados na bolsa + brasileira + - **Índices:** Principais índices do mercado brasileiro (Ibovespa, IBrX, IFIX, + etc.) + - **Filtro por Nome:** Use `search` para filtrar por código ou nome do ativo - Requer token de autenticação via `token` (query) ou `Authorization` (header). + ### Características - ### Exemplo de Requisição: + - **Sem Autenticação:** Este endpoint é **público** e não requer token + - **Cache:** Dados cacheados por 15 minutos + - **Atualização automática:** Conforme novos ativos são listados na B3 - **Listar todos os tickers disponíveis:** + ### Exemplos de Uso ```bash - curl -X GET "https://brapi.dev/api/available?token=SEU_TOKEN" - ``` + # Listar todos os ativos + curl "https://brapi.dev/api/available" - **Buscar tickers que contenham 'BBDC':** + # Buscar por código de ticker + curl "https://brapi.dev/api/available?search=PETR" - ```bash - curl -X GET "https://brapi.dev/api/available?search=BBDC&token=SEU_TOKEN" + # Buscar por nome da empresa + curl "https://brapi.dev/api/available?search=banco" ``` - ### Resposta: + ### Índices Disponíveis - A resposta é um objeto JSON com duas chaves: + - `^BVSP` — Ibovespa (Índice Bovespa) + - `^IBX50` — IBrX 50 + - `^IBX100` — IBrX 100 + - `^IDIV` — Índice Dividendos + - `^SMLL` — Índice Small Cap + - `^IFIX` — Índice de Fundos Imobiliários + - `^IFNC` — Índice Financeiro + - `^ICON` — Índice de Consumo + - `^IEEX` — Índice de Energia Elétrica + - `^IMOB` — Índice Imobiliário - - `indexes`: Array de strings contendo os tickers dos índices disponíveis (ex: - `["^BVSP", "^IFIX"]`). - - `stocks`: Array de strings contendo os tickers das ações, FIIs, BDRs e ETFs - disponíveis (ex: `["PETR4", "VALE3", "ITSA4", "MXRF11"]`). + ### Campos da Resposta - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + - `stocks` — Array com códigos das ações (ex: ["PETR4", "VALE3", "ITUB4", ...]) + - `indexes` — Array com códigos dos índices (ex: ["^BVSP", "^IFIX", ...]) + + ### Como Usar - **Formas de Envio:** + Use os códigos retornados como parâmetro no endpoint `/api/quote/{tickers}` para + obter cotações detalhadas. - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + **Fonte:** B3 (Bolsa de Valores do Brasil) - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + **Plano Mínimo:** Gratuito **Autenticação:** Não necessária (Público) - search: **Opcional.** Termo para filtrar a lista de tickers (correspondência parcial, - case-insensitive). Se omitido, retorna todos os tickers. + Args: + search: Filtrar ações e índices por nome ou código extra_headers: Send extra headers @@ -235,13 +249,7 @@ async def list( extra_query=extra_query, extra_body=extra_body, timeout=timeout, - query=await async_maybe_transform( - { - "token": token, - "search": search, - }, - available_list_params.AvailableListParams, - ), + query=await async_maybe_transform({"search": search}, available_list_params.AvailableListParams), ), cast_to=AvailableListResponse, ) diff --git a/src/brapi/resources/quote.py b/src/brapi/resources/quote.py index ba428d5..391d46f 100644 --- a/src/brapi/resources/quote.py +++ b/src/brapi/resources/quote.py @@ -2,14 +2,13 @@ from __future__ import annotations -from typing import List from typing_extensions import Literal import httpx from ..types import quote_list_params, quote_retrieve_params from .._types import Body, Omit, Query, Headers, NotGiven, omit, not_given -from .._utils import maybe_transform, async_maybe_transform +from .._utils import path_template, maybe_transform, async_maybe_transform from .._compat import cached_property from .._resource import SyncAPIResource, AsyncAPIResource from .._response import ( @@ -26,6 +25,11 @@ class QuoteResource(SyncAPIResource): + """Consulte informações detalhadas sobre ações, BDRs, ETFs e índices da B3. + + Obtenha preços em tempo real, dados fundamentalistas, históricos e dividendos. + """ + @cached_property def with_raw_response(self) -> QuoteResourceWithRawResponse: """ @@ -50,31 +54,14 @@ def retrieve( tickers: str, *, token: str | Omit = omit, - dividends: bool | Omit = omit, - fundamental: bool | Omit = omit, + dividends: Literal["true", "false"] | Omit = omit, + end_date: str | Omit = omit, interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] | Omit = omit, - modules: List[ - Literal[ - "summaryProfile", - "balanceSheetHistory", - "defaultKeyStatistics", - "balanceSheetHistoryQuarterly", - "incomeStatementHistory", - "incomeStatementHistoryQuarterly", - "financialData", - "financialDataHistory", - "financialDataHistoryQuarterly", - "defaultKeyStatisticsHistory", - "defaultKeyStatisticsHistoryQuarterly", - "valueAddedHistory", - "valueAddedHistoryQuarterly", - "cashflowHistory", - "cashflowHistoryQuarterly", - ] - ] + modules: str | Omit = omit, + range: Literal["1d", "2d", "5d", "7d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] | Omit = omit, - range: Literal["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] | Omit = omit, + start_date: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -83,210 +70,153 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> QuoteRetrieveResponse: """ - Este endpoint é a principal forma de obter informações detalhadas sobre um ou - mais ativos financeiros (ações, FIIs, ETFs, BDRs, índices) listados na B3, - identificados pelos seus respectivos **tickers**. - - ### Funcionalidades Principais: - - - **Cotação Atual:** Retorna o preço mais recente, variação diária, máximas, - mínimas, volume, etc. - - **Dados Históricos:** Permite solicitar séries históricas de preços usando os - parâmetros `range` e `interval`. - - **Dados Fundamentalistas:** Opcionalmente, inclui dados fundamentalistas - básicos (P/L, LPA) com o parâmetro `fundamental=true`. - - **Dividendos:** Opcionalmente, inclui histórico de dividendos e JCP com - `dividends=true`. - - **Módulos Adicionais:** Permite requisitar conjuntos de dados financeiros mais - aprofundados através do parâmetro `modules` (veja detalhes abaixo). - - ### 🧪 Ações de Teste (Sem Autenticação): - - Para facilitar o desenvolvimento e teste, as seguintes **4 ações têm acesso - irrestrito** e **não requerem autenticação**: + **O ENDPOINT MAIS IMPORTANTE DA API.** Obtém dados detalhados e abrangentes de + um ou múltiplos ativos (ações, FIIs, BDRs) em uma única requisição. Combine + cotações em tempo real, dados históricos, fundamentos e dividendos conforme + necessário. - - **PETR4** (Petrobras PN) - - **MGLU3** (Magazine Luiza ON) - - **VALE3** (Vale ON) - - **ITUB4** (Itaú Unibanco PN) + ### Funcionalidades: - **Importante:** Você pode consultar essas ações sem token e com acesso a todos - os recursos (históricos, módulos, dividendos). Porém, se misturar essas ações - com outras na mesma requisição, a autenticação será obrigatória. + - **Cotação em Tempo Real:** Preço atual, variação absoluta e percentual, + volume, máxima/mínima do dia, range de 52 semanas. + - **Dados Históricos:** Preços OHLCV (Open, High, Low, Close, Volume) com + intervalos flexíveis (1d, 5d, 1wk, 1mo, 3mo) e períodos (1d até max). + - **Fundamentos:** Balanço Patrimonial, DRE, Fluxo de Caixa, DVA, + Indicadores-chave (P/L, P/VP, ROE, etc) via parâmetro `modules`. + - **Dividendos:** Histórico completo de proventos em dinheiro (dividendos, JCP) + e bonificações. ### Autenticação: - Para **outras ações** (além das 4 de teste), é **obrigatório** fornecer um token - de autenticação válido, seja via query parameter `token` ou via header - `Authorization: Bearer seu_token`. - - ### Exemplos de Requisição: - - **1. Cotação simples de PETR4 e VALE3 (ações de teste - sem token):** + Requer token Bearer no header ou como query param. Tickers de teste **PETR4** e + **VALE3** funcionam sem autenticação. ```bash - curl -X GET "https://brapi.dev/api/quote/PETR4,VALE3" - ``` + # Via header (recomendado) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/PETR4" - **2. Cotação de MGLU3 com dados históricos do último mês (ação de teste - sem - token):** - - ```bash - curl -X GET "https://brapi.dev/api/quote/MGLU3?range=1mo&interval=1d" + # Via query param + curl "https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN" ``` - **3. Cotação de ITUB4 incluindo dividendos e dados fundamentalistas (ação de - teste - sem token):** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/quote/ITUB4?fundamental=true÷nds=true" - ``` + # Simples: apenas cotação atual + curl "https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN" - **4. Cotação de WEGE3 com Resumo da Empresa e Balanço Patrimonial Anual (via - módulos - requer token):** + # Múltiplos tickers em uma requisição + curl "https://brapi.dev/api/quote/PETR4,VALE3,ITUB4?token=SEU_TOKEN" - ```bash - curl -X GET "https://brapi.dev/api/quote/WEGE3?modules=summaryProfile,balanceSheetHistory&token=SEU_TOKEN" - ``` + # Com dados históricos (últimos 12 meses, diário) + curl "https://brapi.dev/api/quote/PETR4?range=1y&interval=1d&token=SEU_TOKEN" - **5. Exemplo de requisição mista (requer token):** + # Com módulos de fundamentos (balanço e DRE) + curl "https://brapi.dev/api/quote/PETR4?modules=balanceSheetHistory,incomeStatementHistory&token=SEU_TOKEN" - ```bash - curl -X GET "https://brapi.dev/api/quote/PETR4,BBAS3?token=SEU_TOKEN" + # Completo: histórico + dividendos + estatísticas-chave + curl "https://brapi.dev/api/quote/PETR4?range=6mo&interval=1d÷nds=true&modules=balanceSheetHistory,defaultKeyStatistics&token=SEU_TOKEN" ``` - _Nota: Como BBAS3 não é uma ação de teste, toda a requisição requer - autenticação, mesmo contendo PETR4._ - - ### Parâmetro `modules` (Detalhado): - - O parâmetro `modules` é extremamente poderoso para enriquecer a resposta com - dados financeiros detalhados. Você pode solicitar um ou mais módulos, separados - por vírgula. - - **Módulos Disponíveis:** - - - `summaryProfile`: Informações cadastrais da empresa (endereço, setor, - descrição do negócio, website, número de funcionários). - - `balanceSheetHistory`: Histórico **anual** do Balanço Patrimonial. - - `balanceSheetHistoryQuarterly`: Histórico **trimestral** do Balanço - Patrimonial. - - `defaultKeyStatistics`: Principais estatísticas da empresa (Valor de Mercado, - P/L, ROE, Dividend Yield, etc.) - **TTM (Trailing Twelve Months)**. - - `defaultKeyStatisticsHistory`: Histórico **anual** das Principais - Estatísticas. - - `defaultKeyStatisticsHistoryQuarterly`: Histórico **trimestral** das - Principais Estatísticas. - - `incomeStatementHistory`: Histórico **anual** da Demonstração do Resultado do - Exercício (DRE). - - `incomeStatementHistoryQuarterly`: Histórico **trimestral** da Demonstração do - Resultado do Exercício (DRE). - - `financialData`: Dados financeiros selecionados (Receita, Lucro Bruto, EBITDA, - Dívida Líquida, Fluxo de Caixa Livre, Margens) - **TTM (Trailing Twelve - Months)**. - - `financialDataHistory`: Histórico **anual** dos Dados Financeiros. - - `financialDataHistoryQuarterly`: Histórico **trimestral** dos Dados - Financeiros. - - `valueAddedHistory`: Histórico **anual** da Demonstração do Valor Adicionado - (DVA). - - `valueAddedHistoryQuarterly`: Histórico **trimestral** da Demonstração do - Valor Adicionado (DVA). - - `cashflowHistory`: Histórico **anual** da Demonstração do Fluxo de Caixa - (DFC). - - `cashflowHistoryQuarterly`: Histórico **trimestral** da Demonstração do Fluxo - de Caixa (DFC). - - **Exemplo de Uso do `modules`:** - - Para obter a cotação de BBDC4 junto com seu DRE trimestral e Fluxo de Caixa - anual: - - ```bash - curl -X GET "https://brapi.dev/api/quote/BBDC4?modules=incomeStatementHistoryQuarterly,cashflowHistory&token=SEU_TOKEN" - ``` - - ### Resposta: - - A resposta é um objeto JSON contendo a chave `results`, que é um array. Cada - elemento do array corresponde a um ticker solicitado e contém os dados da - cotação e os módulos adicionais requisitados. - - - **Sucesso (200 OK):** Retorna os dados conforme solicitado. - - **Bad Request (400 Bad Request):** Ocorre se um parâmetro for inválido (ex: - `range=invalid`) ou se a formatação estiver incorreta. - - **Unauthorized (401 Unauthorized):** Token inválido ou ausente. - - **Payment Required (402 Payment Required):** Limite de requisições do plano - atual excedido. - - **Not Found (404 Not Found):** Um ou mais tickers solicitados não foram - encontrados. + ### Módulos Disponíveis: + + - `summaryProfile` — Perfil da empresa (CNPJ, setor, descrição, website, + funcionários) + - `balanceSheetHistory` — Balanço Patrimonial anual + - `balanceSheetHistoryQuarterly` — Balanço Patrimonial trimestral + - `incomeStatementHistory` — DRE anual (Demonstração de Resultado do Exercício) + - `incomeStatementHistoryQuarterly` — DRE trimestral + - `financialData` — Indicadores financeiros atuais (TTM - Trailing Twelve + Months) + - `financialDataHistory` — Histórico anual de indicadores financeiros + - `financialDataHistoryQuarterly` — Histórico trimestral de indicadores + financeiros + - `defaultKeyStatistics` — Estatísticas-chave (P/L, P/VP, ROE, Dividend Yield, + etc) + - `defaultKeyStatisticsHistory` — Histórico anual de estatísticas-chave + - `defaultKeyStatisticsHistoryQuarterly` — Histórico trimestral de + estatísticas-chave + - `cashflowHistory` — Fluxo de Caixa anual + - `cashflowHistoryQuarterly` — Fluxo de Caixa trimestral + - `valueAddedHistory` — DVA anual (Demonstração de Valor Adicionado) + - `valueAddedHistoryQuarterly` — DVA trimestral + + ### Intervalos Válidos (histórico): + + - `1d` — Diário + - `5d` — 5 dias + - `1wk` — Semanal + - `1mo` — Mensal + - `3mo` — Trimestral + + ### Períodos Válidos (range): + + - `1d` — Último dia + - `5d` — Últimos 5 dias + - `1mo` — Último mês + - `3mo` — Últimos 3 meses + - `6mo` — Últimos 6 meses + - `1y` — Último ano + - `2y` — Últimos 2 anos + - `5y` — Últimos 5 anos + - `10y` — Últimos 10 anos + - `ytd` — Ano até hoje + - `max` — Máximo disponível + + ### Campos Principais da Resposta: + + - `symbol` — Ticker do ativo (ex: PETR4) + - `shortName` — Nome curto da empresa + - `currency` — Moeda (BRL) + - `regularMarketPrice` — Preço atual em BRL + - `regularMarketChange` — Variação absoluta + - `regularMarketChangePercent` — Variação percentual (%) + - `regularMarketVolume` — Volume de negociação do dia + - `regularMarketDayHigh` — Máxima do dia + - `regularMarketDayLow` — Mínima do dia + - `fiftyTwoWeekHigh` — Máxima de 52 semanas + - `fiftyTwoWeekLow` — Mínima de 52 semanas + - `marketCap` — Capitalização de mercado + - `historicalDataPrice` — Array de dados OHLCV (quando `range`/`interval` + fornecidos) + - `dividendsData` — Histórico de dividendos (quando `dividends=true`) + + ### Tickers Populares (Teste): + + - `PETR4` — Petrobras (Energia) + - `VALE3` — Vale (Mineração) + - `ITUB4` — Itaú Unibanco (Financeiro) + - `BBDC4` — Bradesco (Financeiro) + - `ABEV3` — Ambev (Consumo) + - `WEGE3` — WEG (Indústria) + - `RENT3` — Localiza (Transporte) + - `BBAS3` — Banco do Brasil (Financeiro) + - `MGLU3` — Magazine Luiza (Varejo) + + ### Fonte dos Dados: + + B3 (Bolsa de Valores do Brasil), CVM (Comissão de Valores Mobiliários) + + **Plano Mínimo:** Gratuito (limitado a 1 ticker/requisição e módulos básicos) + **Autenticação:** Necessária para produção (tickers de teste PETR4 e VALE3 + funcionam sem token) Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - dividends: **Opcional.** Booleano (`true` ou `false`). Se `true`, inclui informações sobre - dividendos e JCP (Juros sobre Capital Próprio) pagos historicamente pelo ativo - na chave `dividendsData`. - - fundamental: **Opcional.** Booleano (`true` ou `false`). Se `true`, inclui dados - fundamentalistas básicos na resposta, como Preço/Lucro (P/L) e Lucro Por Ação - (LPA). - - **Nota:** Para dados fundamentalistas mais completos, utilize o parâmetro - `modules`. - - interval: **Opcional.** Define a granularidade (intervalo) dos dados históricos de preço - (`historicalDataPrice`). Requer que `range` também seja especificado. + tickers: Ticker(s) de ativos separados por vírgula (ex: PETR4 ou PETR4,VALE3,ITUB4) - **Valores Possíveis:** + token: Token de autenticação (alternativa ao header Authorization) - - `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`: Intervalos intraday - (minutos/horas). **Atenção:** Disponibilidade pode variar conforme o `range` e - o ativo. - - `1d`: Diário (padrão se `range` for especificado e `interval` omitido). - - `5d`: 5 dias. - - `1wk`: Semanal. - - `1mo`: Mensal. - - `3mo`: Trimestral. + dividends: Incluir histórico de dividendos e JCP - modules: **Opcional.** Uma lista de módulos de dados adicionais, separados por vírgula - (`,`), para incluir na resposta. Permite buscar dados financeiros detalhados. + end_date: Data final para dados históricos (formato YYYY-MM-DD) - **Exemplos:** + interval: Intervalo/granularidade dos dados históricos - - `modules=summaryProfile` (retorna perfil da empresa) - - `modules=balanceSheetHistory,incomeStatementHistory` (retorna histórico anual - do BP e DRE) + modules: Módulos de dados adicionais separados por vírgula - Veja a descrição principal do endpoint para a lista completa de módulos e seus - conteúdos. + range: Período para dados históricos de preço - range: **Opcional.** Define o período para os dados históricos de preço - (`historicalDataPrice`). Se omitido, apenas a cotação mais recente é retornada - (a menos que `interval` seja usado). - - **Valores Possíveis:** - - - `1d`: Último dia de pregão (intraday se `interval` for minutos/horas). - - `5d`: Últimos 5 dias. - - `1mo`: Último mês. - - `3mo`: Últimos 3 meses. - - `6mo`: Últimos 6 meses. - - `1y`: Último ano. - - `2y`: Últimos 2 anos. - - `5y`: Últimos 5 anos. - - `10y`: Últimos 10 anos. - - `ytd`: Desde o início do ano atual (Year-to-Date). - - `max`: Todo o período histórico disponível. + start_date: Data inicial para dados históricos (formato YYYY-MM-DD) extra_headers: Send extra headers @@ -299,7 +229,7 @@ def retrieve( if not tickers: raise ValueError(f"Expected a non-empty value for `tickers` but received {tickers!r}") return self._get( - f"/api/quote/{tickers}", + path_template("/api/quote/{tickers}", tickers=tickers), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, @@ -309,10 +239,11 @@ def retrieve( { "token": token, "dividends": dividends, - "fundamental": fundamental, + "end_date": end_date, "interval": interval, "modules": modules, "range": range, + "start_date": start_date, }, quote_retrieve_params.QuoteRetrieveParams, ), @@ -324,33 +255,11 @@ def list( self, *, token: str | Omit = omit, - limit: int | Omit = omit, - page: int | Omit = omit, + limit: str | Omit = omit, + page: str | Omit = omit, search: str | Omit = omit, - sector: Literal[ - "Retail Trade", - "Energy Minerals", - "Health Services", - "Utilities", - "Finance", - "Consumer Services", - "Consumer Non-Durables", - "Non-Energy Minerals", - "Commercial Services", - "Distribution Services", - "Transportation", - "Technology Services", - "Process Industries", - "Communications", - "Producer Manufacturing", - "Miscellaneous", - "Electronic Technology", - "Industrial Services", - "Health Technology", - "Consumer Durables", - ] - | Omit = omit, - sort_by: Literal["name", "close", "change", "change_abs", "volume", "market_cap_basic", "sector"] | Omit = omit, + sector: str | Omit = omit, + sort_by: Literal["name", "close", "change", "change_abs", "volume", "market_cap_basic"] | Omit = omit, sort_order: Literal["asc", "desc"] | Omit = omit, type: Literal["stock", "fund", "bdr"] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. @@ -361,79 +270,71 @@ def list( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> QuoteListResponse: """ - Obtenha uma lista paginada de cotações de diversos ativos (ações, FIIs, BDRs) - negociados na B3, com opções avançadas de busca, filtragem e ordenação. + Retorna uma lista paginada de todos os ativos disponíveis na API (Ações, FIIs, + BDRs, ETFs, Índices). Use este endpoint para construir screeners, exploradores + de ações ou para descobrir novos ativos. ### Funcionalidades: - - **Busca por Ticker:** Filtre por parte do ticker usando `search`. - - **Filtragem por Tipo:** Restrinja a lista a `stock`, `fund` (FII) ou `bdr` com - o parâmetro `type`. - - **Filtragem por Setor:** Selecione ativos de um setor específico usando - `sector`. - - **Ordenação:** Ordene os resultados por diversos campos (preço, variação, - volume, etc.) usando `sortBy` e `sortOrder`. - - **Paginação:** Controle o número de resultados por página (`limit`) e a página - desejada (`page`). + - **Busca por Nome ou Ticker:** Encontre ativos digitando "Petrobras", "PETR4" + ou qualquer termo. + - **Filtros por Tipo:** Ações (stock), Fundos Imobiliários (fund), BDRs (bdr). + - **Filtros por Setor:** Energia, Financeiro, Tecnologia, Saúde, etc. + - **Ordenação Flexível:** Ordene por volume, preço, market cap ou nome. + - **Paginação:** Controle o número de resultados com `limit` e `page`. ### Autenticação: - Requer token de autenticação via `token` (query) ou `Authorization` (header). + Requer token Bearer. Obtenha seu token em + [brapi.dev/dashboard](https://brapi.dev/dashboard). - ### Exemplo de Requisição: - - **Listar as 10 ações do setor Financeiro com maior volume, ordenadas de forma - decrescente:** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/quote/list?sector=Finance&sortBy=volume&sortOrder=desc&limit=10&page=1&token=SEU_TOKEN" - ``` + # Listar todos os ativos (primeiros 100) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list" - **Buscar por ativos cujo ticker contenha 'ITUB' e ordenar por nome ascendente:** + # Buscar por nome ou ticker + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?search=petrobras" - ```bash - curl -X GET "https://brapi.dev/api/quote/list?search=ITUB&sortBy=name&sortOrder=asc&token=SEU_TOKEN" + # Filtrar por tipo e ordenar por volume + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?type=stock&sortBy=volume&sortOrder=desc&limit=10" + + # Listar apenas FIIs de um setor específico + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?type=fund§or=Logística&limit=20" ``` - ### Resposta: + ### Parâmetros de Ordenação: - A resposta contém a lista de `stocks` (e `indexes` relevantes), informações - sobre os filtros aplicados, detalhes da paginação (`currentPage`, `totalPages`, - `itemsPerPage`, `totalCount`, `hasNextPage`) e listas de setores - (`availableSectors`) e tipos (`availableStockTypes`) disponíveis para filtragem. + - `volume` — Volume de negociação do dia + - `close` — Preço de fechamento + - `market_cap_basic` — Capitalização de mercado + - `name` — Nome da empresa (alfabético) - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + ### Tipos de Ativo: - **Formas de Envio:** + - `stock` — Ações (Ações ordinárias e preferenciais) + - `fund` — Fundos Imobiliários (FIIs) e ETFs + - `bdr` — BDRs (Brazilian Depositary Receipts) - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + **Plano Mínimo:** Gratuito **Autenticação:** Necessária (Bearer Token) - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + Args: + token: Token de autenticação (alternativa ao header Authorization) - limit: **Opcional.** Número máximo de ativos a serem retornados por página. O valor - padrão pode variar. + limit: Número máximo de resultados - page: **Opcional.** Número da página dos resultados a ser retornada, considerando o - `limit` especificado. Começa em 1. + page: Número da página (paginação) - search: - **Opcional.** Termo para buscar ativos por ticker (correspondência parcial). Ex: - `PETR` encontrará `PETR4`, `PETR3`. + search: Termo de busca para filtrar ativos - sector: **Opcional.** Filtra os resultados por setor de atuação da empresa. Utilize um - dos valores retornados em `availableSectors`. + sector: Filtrar por setor - sort_by: **Opcional.** Campo pelo qual os resultados serão ordenados. + sort_by: Campo para ordenação - sort_order: **Opcional.** Direção da ordenação: `asc` (ascendente) ou `desc` (descendente). - Requer que `sortBy` seja especificado. + sort_order: Ordem de classificação - type: **Opcional.** Filtra os resultados por tipo de ativo. + type: Filtrar por tipo de ativo extra_headers: Send extra headers @@ -469,6 +370,11 @@ def list( class AsyncQuoteResource(AsyncAPIResource): + """Consulte informações detalhadas sobre ações, BDRs, ETFs e índices da B3. + + Obtenha preços em tempo real, dados fundamentalistas, históricos e dividendos. + """ + @cached_property def with_raw_response(self) -> AsyncQuoteResourceWithRawResponse: """ @@ -493,31 +399,14 @@ async def retrieve( tickers: str, *, token: str | Omit = omit, - dividends: bool | Omit = omit, - fundamental: bool | Omit = omit, + dividends: Literal["true", "false"] | Omit = omit, + end_date: str | Omit = omit, interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] | Omit = omit, - modules: List[ - Literal[ - "summaryProfile", - "balanceSheetHistory", - "defaultKeyStatistics", - "balanceSheetHistoryQuarterly", - "incomeStatementHistory", - "incomeStatementHistoryQuarterly", - "financialData", - "financialDataHistory", - "financialDataHistoryQuarterly", - "defaultKeyStatisticsHistory", - "defaultKeyStatisticsHistoryQuarterly", - "valueAddedHistory", - "valueAddedHistoryQuarterly", - "cashflowHistory", - "cashflowHistoryQuarterly", - ] - ] + modules: str | Omit = omit, + range: Literal["1d", "2d", "5d", "7d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] | Omit = omit, - range: Literal["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] | Omit = omit, + start_date: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -526,210 +415,153 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> QuoteRetrieveResponse: """ - Este endpoint é a principal forma de obter informações detalhadas sobre um ou - mais ativos financeiros (ações, FIIs, ETFs, BDRs, índices) listados na B3, - identificados pelos seus respectivos **tickers**. - - ### Funcionalidades Principais: - - - **Cotação Atual:** Retorna o preço mais recente, variação diária, máximas, - mínimas, volume, etc. - - **Dados Históricos:** Permite solicitar séries históricas de preços usando os - parâmetros `range` e `interval`. - - **Dados Fundamentalistas:** Opcionalmente, inclui dados fundamentalistas - básicos (P/L, LPA) com o parâmetro `fundamental=true`. - - **Dividendos:** Opcionalmente, inclui histórico de dividendos e JCP com - `dividends=true`. - - **Módulos Adicionais:** Permite requisitar conjuntos de dados financeiros mais - aprofundados através do parâmetro `modules` (veja detalhes abaixo). - - ### 🧪 Ações de Teste (Sem Autenticação): - - Para facilitar o desenvolvimento e teste, as seguintes **4 ações têm acesso - irrestrito** e **não requerem autenticação**: + **O ENDPOINT MAIS IMPORTANTE DA API.** Obtém dados detalhados e abrangentes de + um ou múltiplos ativos (ações, FIIs, BDRs) em uma única requisição. Combine + cotações em tempo real, dados históricos, fundamentos e dividendos conforme + necessário. - - **PETR4** (Petrobras PN) - - **MGLU3** (Magazine Luiza ON) - - **VALE3** (Vale ON) - - **ITUB4** (Itaú Unibanco PN) + ### Funcionalidades: - **Importante:** Você pode consultar essas ações sem token e com acesso a todos - os recursos (históricos, módulos, dividendos). Porém, se misturar essas ações - com outras na mesma requisição, a autenticação será obrigatória. + - **Cotação em Tempo Real:** Preço atual, variação absoluta e percentual, + volume, máxima/mínima do dia, range de 52 semanas. + - **Dados Históricos:** Preços OHLCV (Open, High, Low, Close, Volume) com + intervalos flexíveis (1d, 5d, 1wk, 1mo, 3mo) e períodos (1d até max). + - **Fundamentos:** Balanço Patrimonial, DRE, Fluxo de Caixa, DVA, + Indicadores-chave (P/L, P/VP, ROE, etc) via parâmetro `modules`. + - **Dividendos:** Histórico completo de proventos em dinheiro (dividendos, JCP) + e bonificações. ### Autenticação: - Para **outras ações** (além das 4 de teste), é **obrigatório** fornecer um token - de autenticação válido, seja via query parameter `token` ou via header - `Authorization: Bearer seu_token`. - - ### Exemplos de Requisição: - - **1. Cotação simples de PETR4 e VALE3 (ações de teste - sem token):** + Requer token Bearer no header ou como query param. Tickers de teste **PETR4** e + **VALE3** funcionam sem autenticação. ```bash - curl -X GET "https://brapi.dev/api/quote/PETR4,VALE3" - ``` + # Via header (recomendado) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/PETR4" - **2. Cotação de MGLU3 com dados históricos do último mês (ação de teste - sem - token):** - - ```bash - curl -X GET "https://brapi.dev/api/quote/MGLU3?range=1mo&interval=1d" + # Via query param + curl "https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN" ``` - **3. Cotação de ITUB4 incluindo dividendos e dados fundamentalistas (ação de - teste - sem token):** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/quote/ITUB4?fundamental=true÷nds=true" - ``` + # Simples: apenas cotação atual + curl "https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN" - **4. Cotação de WEGE3 com Resumo da Empresa e Balanço Patrimonial Anual (via - módulos - requer token):** + # Múltiplos tickers em uma requisição + curl "https://brapi.dev/api/quote/PETR4,VALE3,ITUB4?token=SEU_TOKEN" - ```bash - curl -X GET "https://brapi.dev/api/quote/WEGE3?modules=summaryProfile,balanceSheetHistory&token=SEU_TOKEN" - ``` + # Com dados históricos (últimos 12 meses, diário) + curl "https://brapi.dev/api/quote/PETR4?range=1y&interval=1d&token=SEU_TOKEN" - **5. Exemplo de requisição mista (requer token):** + # Com módulos de fundamentos (balanço e DRE) + curl "https://brapi.dev/api/quote/PETR4?modules=balanceSheetHistory,incomeStatementHistory&token=SEU_TOKEN" - ```bash - curl -X GET "https://brapi.dev/api/quote/PETR4,BBAS3?token=SEU_TOKEN" + # Completo: histórico + dividendos + estatísticas-chave + curl "https://brapi.dev/api/quote/PETR4?range=6mo&interval=1d÷nds=true&modules=balanceSheetHistory,defaultKeyStatistics&token=SEU_TOKEN" ``` - _Nota: Como BBAS3 não é uma ação de teste, toda a requisição requer - autenticação, mesmo contendo PETR4._ - - ### Parâmetro `modules` (Detalhado): - - O parâmetro `modules` é extremamente poderoso para enriquecer a resposta com - dados financeiros detalhados. Você pode solicitar um ou mais módulos, separados - por vírgula. - - **Módulos Disponíveis:** - - - `summaryProfile`: Informações cadastrais da empresa (endereço, setor, - descrição do negócio, website, número de funcionários). - - `balanceSheetHistory`: Histórico **anual** do Balanço Patrimonial. - - `balanceSheetHistoryQuarterly`: Histórico **trimestral** do Balanço - Patrimonial. - - `defaultKeyStatistics`: Principais estatísticas da empresa (Valor de Mercado, - P/L, ROE, Dividend Yield, etc.) - **TTM (Trailing Twelve Months)**. - - `defaultKeyStatisticsHistory`: Histórico **anual** das Principais - Estatísticas. - - `defaultKeyStatisticsHistoryQuarterly`: Histórico **trimestral** das - Principais Estatísticas. - - `incomeStatementHistory`: Histórico **anual** da Demonstração do Resultado do - Exercício (DRE). - - `incomeStatementHistoryQuarterly`: Histórico **trimestral** da Demonstração do - Resultado do Exercício (DRE). - - `financialData`: Dados financeiros selecionados (Receita, Lucro Bruto, EBITDA, - Dívida Líquida, Fluxo de Caixa Livre, Margens) - **TTM (Trailing Twelve - Months)**. - - `financialDataHistory`: Histórico **anual** dos Dados Financeiros. - - `financialDataHistoryQuarterly`: Histórico **trimestral** dos Dados - Financeiros. - - `valueAddedHistory`: Histórico **anual** da Demonstração do Valor Adicionado - (DVA). - - `valueAddedHistoryQuarterly`: Histórico **trimestral** da Demonstração do - Valor Adicionado (DVA). - - `cashflowHistory`: Histórico **anual** da Demonstração do Fluxo de Caixa - (DFC). - - `cashflowHistoryQuarterly`: Histórico **trimestral** da Demonstração do Fluxo - de Caixa (DFC). - - **Exemplo de Uso do `modules`:** - - Para obter a cotação de BBDC4 junto com seu DRE trimestral e Fluxo de Caixa - anual: - - ```bash - curl -X GET "https://brapi.dev/api/quote/BBDC4?modules=incomeStatementHistoryQuarterly,cashflowHistory&token=SEU_TOKEN" - ``` - - ### Resposta: - - A resposta é um objeto JSON contendo a chave `results`, que é um array. Cada - elemento do array corresponde a um ticker solicitado e contém os dados da - cotação e os módulos adicionais requisitados. - - - **Sucesso (200 OK):** Retorna os dados conforme solicitado. - - **Bad Request (400 Bad Request):** Ocorre se um parâmetro for inválido (ex: - `range=invalid`) ou se a formatação estiver incorreta. - - **Unauthorized (401 Unauthorized):** Token inválido ou ausente. - - **Payment Required (402 Payment Required):** Limite de requisições do plano - atual excedido. - - **Not Found (404 Not Found):** Um ou mais tickers solicitados não foram - encontrados. + ### Módulos Disponíveis: + + - `summaryProfile` — Perfil da empresa (CNPJ, setor, descrição, website, + funcionários) + - `balanceSheetHistory` — Balanço Patrimonial anual + - `balanceSheetHistoryQuarterly` — Balanço Patrimonial trimestral + - `incomeStatementHistory` — DRE anual (Demonstração de Resultado do Exercício) + - `incomeStatementHistoryQuarterly` — DRE trimestral + - `financialData` — Indicadores financeiros atuais (TTM - Trailing Twelve + Months) + - `financialDataHistory` — Histórico anual de indicadores financeiros + - `financialDataHistoryQuarterly` — Histórico trimestral de indicadores + financeiros + - `defaultKeyStatistics` — Estatísticas-chave (P/L, P/VP, ROE, Dividend Yield, + etc) + - `defaultKeyStatisticsHistory` — Histórico anual de estatísticas-chave + - `defaultKeyStatisticsHistoryQuarterly` — Histórico trimestral de + estatísticas-chave + - `cashflowHistory` — Fluxo de Caixa anual + - `cashflowHistoryQuarterly` — Fluxo de Caixa trimestral + - `valueAddedHistory` — DVA anual (Demonstração de Valor Adicionado) + - `valueAddedHistoryQuarterly` — DVA trimestral + + ### Intervalos Válidos (histórico): + + - `1d` — Diário + - `5d` — 5 dias + - `1wk` — Semanal + - `1mo` — Mensal + - `3mo` — Trimestral + + ### Períodos Válidos (range): + + - `1d` — Último dia + - `5d` — Últimos 5 dias + - `1mo` — Último mês + - `3mo` — Últimos 3 meses + - `6mo` — Últimos 6 meses + - `1y` — Último ano + - `2y` — Últimos 2 anos + - `5y` — Últimos 5 anos + - `10y` — Últimos 10 anos + - `ytd` — Ano até hoje + - `max` — Máximo disponível + + ### Campos Principais da Resposta: + + - `symbol` — Ticker do ativo (ex: PETR4) + - `shortName` — Nome curto da empresa + - `currency` — Moeda (BRL) + - `regularMarketPrice` — Preço atual em BRL + - `regularMarketChange` — Variação absoluta + - `regularMarketChangePercent` — Variação percentual (%) + - `regularMarketVolume` — Volume de negociação do dia + - `regularMarketDayHigh` — Máxima do dia + - `regularMarketDayLow` — Mínima do dia + - `fiftyTwoWeekHigh` — Máxima de 52 semanas + - `fiftyTwoWeekLow` — Mínima de 52 semanas + - `marketCap` — Capitalização de mercado + - `historicalDataPrice` — Array de dados OHLCV (quando `range`/`interval` + fornecidos) + - `dividendsData` — Histórico de dividendos (quando `dividends=true`) + + ### Tickers Populares (Teste): + + - `PETR4` — Petrobras (Energia) + - `VALE3` — Vale (Mineração) + - `ITUB4` — Itaú Unibanco (Financeiro) + - `BBDC4` — Bradesco (Financeiro) + - `ABEV3` — Ambev (Consumo) + - `WEGE3` — WEG (Indústria) + - `RENT3` — Localiza (Transporte) + - `BBAS3` — Banco do Brasil (Financeiro) + - `MGLU3` — Magazine Luiza (Varejo) + + ### Fonte dos Dados: + + B3 (Bolsa de Valores do Brasil), CVM (Comissão de Valores Mobiliários) + + **Plano Mínimo:** Gratuito (limitado a 1 ticker/requisição e módulos básicos) + **Autenticação:** Necessária para produção (tickers de teste PETR4 e VALE3 + funcionam sem token) Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - dividends: **Opcional.** Booleano (`true` ou `false`). Se `true`, inclui informações sobre - dividendos e JCP (Juros sobre Capital Próprio) pagos historicamente pelo ativo - na chave `dividendsData`. - - fundamental: **Opcional.** Booleano (`true` ou `false`). Se `true`, inclui dados - fundamentalistas básicos na resposta, como Preço/Lucro (P/L) e Lucro Por Ação - (LPA). - - **Nota:** Para dados fundamentalistas mais completos, utilize o parâmetro - `modules`. - - interval: **Opcional.** Define a granularidade (intervalo) dos dados históricos de preço - (`historicalDataPrice`). Requer que `range` também seja especificado. + tickers: Ticker(s) de ativos separados por vírgula (ex: PETR4 ou PETR4,VALE3,ITUB4) - **Valores Possíveis:** + token: Token de autenticação (alternativa ao header Authorization) - - `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`: Intervalos intraday - (minutos/horas). **Atenção:** Disponibilidade pode variar conforme o `range` e - o ativo. - - `1d`: Diário (padrão se `range` for especificado e `interval` omitido). - - `5d`: 5 dias. - - `1wk`: Semanal. - - `1mo`: Mensal. - - `3mo`: Trimestral. + dividends: Incluir histórico de dividendos e JCP - modules: **Opcional.** Uma lista de módulos de dados adicionais, separados por vírgula - (`,`), para incluir na resposta. Permite buscar dados financeiros detalhados. + end_date: Data final para dados históricos (formato YYYY-MM-DD) - **Exemplos:** + interval: Intervalo/granularidade dos dados históricos - - `modules=summaryProfile` (retorna perfil da empresa) - - `modules=balanceSheetHistory,incomeStatementHistory` (retorna histórico anual - do BP e DRE) + modules: Módulos de dados adicionais separados por vírgula - Veja a descrição principal do endpoint para a lista completa de módulos e seus - conteúdos. + range: Período para dados históricos de preço - range: **Opcional.** Define o período para os dados históricos de preço - (`historicalDataPrice`). Se omitido, apenas a cotação mais recente é retornada - (a menos que `interval` seja usado). - - **Valores Possíveis:** - - - `1d`: Último dia de pregão (intraday se `interval` for minutos/horas). - - `5d`: Últimos 5 dias. - - `1mo`: Último mês. - - `3mo`: Últimos 3 meses. - - `6mo`: Últimos 6 meses. - - `1y`: Último ano. - - `2y`: Últimos 2 anos. - - `5y`: Últimos 5 anos. - - `10y`: Últimos 10 anos. - - `ytd`: Desde o início do ano atual (Year-to-Date). - - `max`: Todo o período histórico disponível. + start_date: Data inicial para dados históricos (formato YYYY-MM-DD) extra_headers: Send extra headers @@ -742,7 +574,7 @@ async def retrieve( if not tickers: raise ValueError(f"Expected a non-empty value for `tickers` but received {tickers!r}") return await self._get( - f"/api/quote/{tickers}", + path_template("/api/quote/{tickers}", tickers=tickers), options=make_request_options( extra_headers=extra_headers, extra_query=extra_query, @@ -752,10 +584,11 @@ async def retrieve( { "token": token, "dividends": dividends, - "fundamental": fundamental, + "end_date": end_date, "interval": interval, "modules": modules, "range": range, + "start_date": start_date, }, quote_retrieve_params.QuoteRetrieveParams, ), @@ -767,33 +600,11 @@ async def list( self, *, token: str | Omit = omit, - limit: int | Omit = omit, - page: int | Omit = omit, + limit: str | Omit = omit, + page: str | Omit = omit, search: str | Omit = omit, - sector: Literal[ - "Retail Trade", - "Energy Minerals", - "Health Services", - "Utilities", - "Finance", - "Consumer Services", - "Consumer Non-Durables", - "Non-Energy Minerals", - "Commercial Services", - "Distribution Services", - "Transportation", - "Technology Services", - "Process Industries", - "Communications", - "Producer Manufacturing", - "Miscellaneous", - "Electronic Technology", - "Industrial Services", - "Health Technology", - "Consumer Durables", - ] - | Omit = omit, - sort_by: Literal["name", "close", "change", "change_abs", "volume", "market_cap_basic", "sector"] | Omit = omit, + sector: str | Omit = omit, + sort_by: Literal["name", "close", "change", "change_abs", "volume", "market_cap_basic"] | Omit = omit, sort_order: Literal["asc", "desc"] | Omit = omit, type: Literal["stock", "fund", "bdr"] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. @@ -804,79 +615,71 @@ async def list( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> QuoteListResponse: """ - Obtenha uma lista paginada de cotações de diversos ativos (ações, FIIs, BDRs) - negociados na B3, com opções avançadas de busca, filtragem e ordenação. + Retorna uma lista paginada de todos os ativos disponíveis na API (Ações, FIIs, + BDRs, ETFs, Índices). Use este endpoint para construir screeners, exploradores + de ações ou para descobrir novos ativos. ### Funcionalidades: - - **Busca por Ticker:** Filtre por parte do ticker usando `search`. - - **Filtragem por Tipo:** Restrinja a lista a `stock`, `fund` (FII) ou `bdr` com - o parâmetro `type`. - - **Filtragem por Setor:** Selecione ativos de um setor específico usando - `sector`. - - **Ordenação:** Ordene os resultados por diversos campos (preço, variação, - volume, etc.) usando `sortBy` e `sortOrder`. - - **Paginação:** Controle o número de resultados por página (`limit`) e a página - desejada (`page`). + - **Busca por Nome ou Ticker:** Encontre ativos digitando "Petrobras", "PETR4" + ou qualquer termo. + - **Filtros por Tipo:** Ações (stock), Fundos Imobiliários (fund), BDRs (bdr). + - **Filtros por Setor:** Energia, Financeiro, Tecnologia, Saúde, etc. + - **Ordenação Flexível:** Ordene por volume, preço, market cap ou nome. + - **Paginação:** Controle o número de resultados com `limit` e `page`. ### Autenticação: - Requer token de autenticação via `token` (query) ou `Authorization` (header). + Requer token Bearer. Obtenha seu token em + [brapi.dev/dashboard](https://brapi.dev/dashboard). - ### Exemplo de Requisição: - - **Listar as 10 ações do setor Financeiro com maior volume, ordenadas de forma - decrescente:** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/quote/list?sector=Finance&sortBy=volume&sortOrder=desc&limit=10&page=1&token=SEU_TOKEN" - ``` + # Listar todos os ativos (primeiros 100) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list" - **Buscar por ativos cujo ticker contenha 'ITUB' e ordenar por nome ascendente:** + # Buscar por nome ou ticker + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?search=petrobras" - ```bash - curl -X GET "https://brapi.dev/api/quote/list?search=ITUB&sortBy=name&sortOrder=asc&token=SEU_TOKEN" + # Filtrar por tipo e ordenar por volume + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?type=stock&sortBy=volume&sortOrder=desc&limit=10" + + # Listar apenas FIIs de um setor específico + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?type=fund§or=Logística&limit=20" ``` - ### Resposta: + ### Parâmetros de Ordenação: - A resposta contém a lista de `stocks` (e `indexes` relevantes), informações - sobre os filtros aplicados, detalhes da paginação (`currentPage`, `totalPages`, - `itemsPerPage`, `totalCount`, `hasNextPage`) e listas de setores - (`availableSectors`) e tipos (`availableStockTypes`) disponíveis para filtragem. + - `volume` — Volume de negociação do dia + - `close` — Preço de fechamento + - `market_cap_basic` — Capitalização de mercado + - `name` — Nome da empresa (alfabético) - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + ### Tipos de Ativo: - **Formas de Envio:** + - `stock` — Ações (Ações ordinárias e preferenciais) + - `fund` — Fundos Imobiliários (FIIs) e ETFs + - `bdr` — BDRs (Brazilian Depositary Receipts) - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + **Plano Mínimo:** Gratuito **Autenticação:** Necessária (Bearer Token) - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + Args: + token: Token de autenticação (alternativa ao header Authorization) - limit: **Opcional.** Número máximo de ativos a serem retornados por página. O valor - padrão pode variar. + limit: Número máximo de resultados - page: **Opcional.** Número da página dos resultados a ser retornada, considerando o - `limit` especificado. Começa em 1. + page: Número da página (paginação) - search: - **Opcional.** Termo para buscar ativos por ticker (correspondência parcial). Ex: - `PETR` encontrará `PETR4`, `PETR3`. + search: Termo de busca para filtrar ativos - sector: **Opcional.** Filtra os resultados por setor de atuação da empresa. Utilize um - dos valores retornados em `availableSectors`. + sector: Filtrar por setor - sort_by: **Opcional.** Campo pelo qual os resultados serão ordenados. + sort_by: Campo para ordenação - sort_order: **Opcional.** Direção da ordenação: `asc` (ascendente) ou `desc` (descendente). - Requer que `sortBy` seja especificado. + sort_order: Ordem de classificação - type: **Opcional.** Filtra os resultados por tipo de ativo. + type: Filtrar por tipo de ativo extra_headers: Send extra headers diff --git a/src/brapi/resources/v2/crypto.py b/src/brapi/resources/v2/crypto.py index 317e8d9..cec2f9a 100644 --- a/src/brapi/resources/v2/crypto.py +++ b/src/brapi/resources/v2/crypto.py @@ -2,8 +2,6 @@ from __future__ import annotations -from typing_extensions import Literal - import httpx from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given @@ -25,6 +23,10 @@ class CryptoResource(SyncAPIResource): + """ + Obtenha cotações em tempo real e dados históricos de criptomoedas, disponíveis em diversas moedas de referência. + """ + @cached_property def with_raw_response(self) -> CryptoResourceWithRawResponse: """ @@ -47,12 +49,10 @@ def with_streaming_response(self) -> CryptoResourceWithStreamingResponse: def retrieve( self, *, - coin: str, - token: str | Omit = omit, + coin: str | Omit = omit, currency: str | Omit = omit, - interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] - | Omit = omit, - range: Literal["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] | Omit = omit, + interval: str | Omit = omit, + range: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -61,77 +61,54 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CryptoRetrieveResponse: """ - Obtenha cotações atualizadas e dados históricos para uma ou mais criptomoedas. + Retorna cotações atualizadas de uma ou mais criptomoedas, com conversão para + diferentes moedas fiduciárias. ### Funcionalidades: - - **Cotação Múltipla:** Consulte várias criptomoedas em uma única requisição - usando o parâmetro `coin`. - - **Moeda de Referência:** Especifique a moeda fiduciária para a cotação com - `currency` (padrão: BRL). - - **Dados Históricos:** Solicite séries históricas usando `range` e `interval` - (similar ao endpoint de ações). + - **Cotação Atual:** Preço, variação 24h, volume, market cap + - **Múltiplas Moedas:** Consulte várias criptos em uma requisição (separadas por + vírgula) + - **Conversão de Moeda:** BRL (padrão), USD, EUR e outras + - **Dados Históricos:** OHLCV via parâmetros `range` e `interval` ### Autenticação: - Requer token de autenticação via `token` (query) ou `Authorization` (header). - - ### Exemplo de Requisição: - - **Cotação de Bitcoin (BTC) e Ethereum (ETH) em Dólar Americano (USD):** - - ```bash - curl -X GET "https://brapi.dev/api/v2/crypto?coin=BTC,ETH¤cy=USD&token=SEU_TOKEN" - ``` + Bearer token ou query param `token`. Obtenha em brapi.dev/dashboard. - **Cotação de Cardano (ADA) em Real (BRL) com histórico do último mês (intervalo - diário):** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/v2/crypto?coin=ADA¤cy=BRL&range=1mo&interval=1d&token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC¤cy=BRL" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC,ETH,SOL¤cy=USD" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC¤cy=BRL&range=1mo&interval=1d" ``` - ### Resposta: + ### Moedas de Conversão: - A resposta contém um array `coins`, onde cada objeto representa uma criptomoeda - solicitada, incluindo sua cotação atual, dados de mercado e, opcionalmente, a - série histórica (`historicalDataPrice`). + BRL (Real), USD (Dólar), EUR (Euro), GBP (Libra) e outras - Args: - coin: **Obrigatório.** Uma ou mais siglas (tickers) de criptomoedas que você deseja - consultar. Separe múltiplas siglas por vírgula (`,`). - - - **Exemplos:** `BTC`, `ETH,ADA`, `SOL`. - - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** + ### Campos da Resposta: - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + - `coin` — Símbolo da criptomoeda + - `coinName` — Nome completo + - `currency` — Moeda de cotação + - `regularMarketPrice` — Preço atual + - `regularMarketChange` — Variação em valor absoluto + - `regularMarketChangePercent` — Variação percentual (%) + - `regularMarketDayHigh` / `regularMarketDayLow` — Máxima/Mínima do dia + - `regularMarketVolume` — Volume negociado - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + **Plano Mínimo:** Startup **Autenticação:** Necessária - currency: **Opcional.** A sigla da moeda fiduciária na qual a cotação da(s) criptomoeda(s) - deve ser retornada. Se omitido, o padrão é `BRL` (Real Brasileiro). - - interval: **Opcional.** Define a granularidade (intervalo) dos dados históricos de preço - (`historicalDataPrice`). Requer que `range` também seja especificado. Funciona - de forma análoga ao endpoint de ações. + Args: + coin: Sigla(s) das criptomoedas separadas por vírgula - - Valores: `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`, `1d`, `5d`, - `1wk`, `1mo`, `3mo`. + currency: Moeda para cotação (padrão: BRL) - range: **Opcional.** Define o período para os dados históricos de preço - (`historicalDataPrice`). Funciona de forma análoga ao endpoint de ações. Se - omitido, apenas a cotação mais recente é retornada (a menos que `interval` seja - usado). + interval: Intervalo dos dados históricos - - Valores: `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, - `max`. + range: Período para dados históricos extra_headers: Send extra headers @@ -151,7 +128,6 @@ def retrieve( query=maybe_transform( { "coin": coin, - "token": token, "currency": currency, "interval": interval, "range": range, @@ -165,7 +141,6 @@ def retrieve( def list_available( self, *, - token: str | Omit = omit, search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. @@ -175,53 +150,38 @@ def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CryptoListAvailableResponse: """ - Obtenha a lista completa de todas as siglas (tickers) de criptomoedas que a API - Brapi suporta para consulta no endpoint `/api/v2/crypto`. + Retorna a lista de criptomoedas disponíveis para consulta no endpoint + `/api/v2/crypto`. - ### Funcionalidade: + ### Criptomoedas Populares: - - Retorna um array `coins` com as siglas. - - Pode ser filtrado usando o parâmetro `search`. + - **BTC** — Bitcoin + - **ETH** — Ethereum + - **BNB** — Binance Coin + - **SOL** — Solana + - **ADA** — Cardano + - **XRP** — Ripple + - **DOGE** — Dogecoin + - **DOT** — Polkadot + - **MATIC** — Polygon + - **LTC** — Litecoin + - E centenas de outras... - ### Autenticação: + ### Uso: - Requer token de autenticação via `token` (query) ou `Authorization` (header). + Use os símbolos retornados como valor do parâmetro `coin` no endpoint principal. - ### Exemplo de Requisição: - - **Listar todas as criptomoedas disponíveis:** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/v2/crypto/available?token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available?search=BTC" ``` - **Buscar criptomoedas cujo ticker contenha 'DOGE':** - - ```bash - curl -X GET "https://brapi.dev/api/v2/crypto/available?search=DOGE&token=SEU_TOKEN" - ``` - - ### Resposta: - - A resposta é um objeto JSON com a chave `coins`, contendo um array de strings - com as siglas das criptomoedas (ex: `["BTC", "ETH", "LTC", "XRP"]`). + **Plano Mínimo:** Startup **Autenticação:** Necessária Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - search: **Opcional.** Termo para filtrar a lista de siglas de criptomoedas - (correspondência parcial, case-insensitive). Se omitido, retorna todas as - siglas. + search: Filtrar criptomoedas por símbolo extra_headers: Send extra headers @@ -238,19 +198,17 @@ def list_available( extra_query=extra_query, extra_body=extra_body, timeout=timeout, - query=maybe_transform( - { - "token": token, - "search": search, - }, - crypto_list_available_params.CryptoListAvailableParams, - ), + query=maybe_transform({"search": search}, crypto_list_available_params.CryptoListAvailableParams), ), cast_to=CryptoListAvailableResponse, ) class AsyncCryptoResource(AsyncAPIResource): + """ + Obtenha cotações em tempo real e dados históricos de criptomoedas, disponíveis em diversas moedas de referência. + """ + @cached_property def with_raw_response(self) -> AsyncCryptoResourceWithRawResponse: """ @@ -273,12 +231,10 @@ def with_streaming_response(self) -> AsyncCryptoResourceWithStreamingResponse: async def retrieve( self, *, - coin: str, - token: str | Omit = omit, + coin: str | Omit = omit, currency: str | Omit = omit, - interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] - | Omit = omit, - range: Literal["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] | Omit = omit, + interval: str | Omit = omit, + range: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -287,77 +243,54 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CryptoRetrieveResponse: """ - Obtenha cotações atualizadas e dados históricos para uma ou mais criptomoedas. + Retorna cotações atualizadas de uma ou mais criptomoedas, com conversão para + diferentes moedas fiduciárias. ### Funcionalidades: - - **Cotação Múltipla:** Consulte várias criptomoedas em uma única requisição - usando o parâmetro `coin`. - - **Moeda de Referência:** Especifique a moeda fiduciária para a cotação com - `currency` (padrão: BRL). - - **Dados Históricos:** Solicite séries históricas usando `range` e `interval` - (similar ao endpoint de ações). + - **Cotação Atual:** Preço, variação 24h, volume, market cap + - **Múltiplas Moedas:** Consulte várias criptos em uma requisição (separadas por + vírgula) + - **Conversão de Moeda:** BRL (padrão), USD, EUR e outras + - **Dados Históricos:** OHLCV via parâmetros `range` e `interval` ### Autenticação: - Requer token de autenticação via `token` (query) ou `Authorization` (header). + Bearer token ou query param `token`. Obtenha em brapi.dev/dashboard. - ### Exemplo de Requisição: - - **Cotação de Bitcoin (BTC) e Ethereum (ETH) em Dólar Americano (USD):** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/v2/crypto?coin=BTC,ETH¤cy=USD&token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC¤cy=BRL" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC,ETH,SOL¤cy=USD" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC¤cy=BRL&range=1mo&interval=1d" ``` - **Cotação de Cardano (ADA) em Real (BRL) com histórico do último mês (intervalo - diário):** + ### Moedas de Conversão: - ```bash - curl -X GET "https://brapi.dev/api/v2/crypto?coin=ADA¤cy=BRL&range=1mo&interval=1d&token=SEU_TOKEN" - ``` - - ### Resposta: + BRL (Real), USD (Dólar), EUR (Euro), GBP (Libra) e outras - A resposta contém um array `coins`, onde cada objeto representa uma criptomoeda - solicitada, incluindo sua cotação atual, dados de mercado e, opcionalmente, a - série histórica (`historicalDataPrice`). + ### Campos da Resposta: - Args: - coin: **Obrigatório.** Uma ou mais siglas (tickers) de criptomoedas que você deseja - consultar. Separe múltiplas siglas por vírgula (`,`). + - `coin` — Símbolo da criptomoeda + - `coinName` — Nome completo + - `currency` — Moeda de cotação + - `regularMarketPrice` — Preço atual + - `regularMarketChange` — Variação em valor absoluto + - `regularMarketChangePercent` — Variação percentual (%) + - `regularMarketDayHigh` / `regularMarketDayLow` — Máxima/Mínima do dia + - `regularMarketVolume` — Volume negociado - - **Exemplos:** `BTC`, `ETH,ADA`, `SOL`. + **Plano Mínimo:** Startup **Autenticação:** Necessária - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - currency: **Opcional.** A sigla da moeda fiduciária na qual a cotação da(s) criptomoeda(s) - deve ser retornada. Se omitido, o padrão é `BRL` (Real Brasileiro). - - interval: **Opcional.** Define a granularidade (intervalo) dos dados históricos de preço - (`historicalDataPrice`). Requer que `range` também seja especificado. Funciona - de forma análoga ao endpoint de ações. + Args: + coin: Sigla(s) das criptomoedas separadas por vírgula - - Valores: `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`, `1d`, `5d`, - `1wk`, `1mo`, `3mo`. + currency: Moeda para cotação (padrão: BRL) - range: **Opcional.** Define o período para os dados históricos de preço - (`historicalDataPrice`). Funciona de forma análoga ao endpoint de ações. Se - omitido, apenas a cotação mais recente é retornada (a menos que `interval` seja - usado). + interval: Intervalo dos dados históricos - - Valores: `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, - `max`. + range: Período para dados históricos extra_headers: Send extra headers @@ -377,7 +310,6 @@ async def retrieve( query=await async_maybe_transform( { "coin": coin, - "token": token, "currency": currency, "interval": interval, "range": range, @@ -391,7 +323,6 @@ async def retrieve( async def list_available( self, *, - token: str | Omit = omit, search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. @@ -401,53 +332,38 @@ async def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CryptoListAvailableResponse: """ - Obtenha a lista completa de todas as siglas (tickers) de criptomoedas que a API - Brapi suporta para consulta no endpoint `/api/v2/crypto`. + Retorna a lista de criptomoedas disponíveis para consulta no endpoint + `/api/v2/crypto`. - ### Funcionalidade: + ### Criptomoedas Populares: - - Retorna um array `coins` com as siglas. - - Pode ser filtrado usando o parâmetro `search`. + - **BTC** — Bitcoin + - **ETH** — Ethereum + - **BNB** — Binance Coin + - **SOL** — Solana + - **ADA** — Cardano + - **XRP** — Ripple + - **DOGE** — Dogecoin + - **DOT** — Polkadot + - **MATIC** — Polygon + - **LTC** — Litecoin + - E centenas de outras... - ### Autenticação: - - Requer token de autenticação via `token` (query) ou `Authorization` (header). + ### Uso: - ### Exemplo de Requisição: + Use os símbolos retornados como valor do parâmetro `coin` no endpoint principal. - **Listar todas as criptomoedas disponíveis:** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/v2/crypto/available?token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available?search=BTC" ``` - **Buscar criptomoedas cujo ticker contenha 'DOGE':** - - ```bash - curl -X GET "https://brapi.dev/api/v2/crypto/available?search=DOGE&token=SEU_TOKEN" - ``` - - ### Resposta: - - A resposta é um objeto JSON com a chave `coins`, contendo um array de strings - com as siglas das criptomoedas (ex: `["BTC", "ETH", "LTC", "XRP"]`). + **Plano Mínimo:** Startup **Autenticação:** Necessária Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - search: **Opcional.** Termo para filtrar a lista de siglas de criptomoedas - (correspondência parcial, case-insensitive). Se omitido, retorna todas as - siglas. + search: Filtrar criptomoedas por símbolo extra_headers: Send extra headers @@ -465,11 +381,7 @@ async def list_available( extra_body=extra_body, timeout=timeout, query=await async_maybe_transform( - { - "token": token, - "search": search, - }, - crypto_list_available_params.CryptoListAvailableParams, + {"search": search}, crypto_list_available_params.CryptoListAvailableParams ), ), cast_to=CryptoListAvailableResponse, diff --git a/src/brapi/resources/v2/currency.py b/src/brapi/resources/v2/currency.py index 2195980..958e7df 100644 --- a/src/brapi/resources/v2/currency.py +++ b/src/brapi/resources/v2/currency.py @@ -23,6 +23,10 @@ class CurrencyResource(SyncAPIResource): + """ + Monitore taxas de câmbio entre moedas fiduciárias de todo o mundo, com atualizações frequentes e dados históricos. + """ + @cached_property def with_raw_response(self) -> CurrencyResourceWithRawResponse: """ @@ -45,8 +49,7 @@ def with_streaming_response(self) -> CurrencyResourceWithStreamingResponse: def retrieve( self, *, - currency: str, - token: str | Omit = omit, + currency: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -55,49 +58,56 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CurrencyRetrieveResponse: """ - Obtenha cotações atualizadas para um ou mais pares de moedas fiduciárias (ex: - USD-BRL, EUR-USD). + Retorna cotações atualizadas de pares de moedas, com preço de compra/venda, + variação e extremos do dia. ### Funcionalidades: - - **Cotação Múltipla:** Consulte vários pares de moedas em uma única requisição - usando o parâmetro `currency`. - - **Dados Retornados:** Inclui nome do par, preços de compra (bid) e venda - (ask), variação, máximas e mínimas, e timestamp da atualização. + - **Cotação Atual:** Preço de compra (bid), venda (ask), máxima, mínima, + variação + - **Múltiplos Pares:** Consulte vários em uma requisição (separados por vírgula) + - **Formato:** `ORIGEM-DESTINO` (ex: `USD-BRL`) - ### Parâmetros: + ### Autenticação: - - **`currency` (Obrigatório):** Uma lista de pares de moedas separados por - vírgula, no formato `MOEDA_ORIGEM-MOEDA_DESTINO` (ex: `USD-BRL`, `EUR-USD`). - Consulte os pares disponíveis em - [`/api/v2/currency/available`](#/Moedas/getAvailableCurrencies). - - **`token` (Obrigatório):** Seu token de autenticação. + Bearer token ou query param `token`. Obtenha em brapi.dev/dashboard. - ### Autenticação: + ### Exemplos de Requisição: - Requer token de autenticação válido via `token` (query) ou `Authorization` - (header). + ```bash + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=USD-BRL" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=USD-BRL,EUR-BRL,GBP-BRL" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=BTC-BRL" + ``` - Args: - currency: **Obrigatório.** Uma lista de um ou mais pares de moedas a serem consultados, - separados por vírgula (`,`). + ### Pares de Moedas Populares: - - **Formato:** `MOEDA_ORIGEM-MOEDA_DESTINO` (ex: `USD-BRL`). - - **Disponibilidade:** Consulte os pares válidos usando o endpoint - [`/api/v2/currency/available`](#/Moedas/getAvailableCurrencies). - - **Exemplo:** `USD-BRL,EUR-BRL,BTC-BRL` + - `USD-BRL` — Dólar Americano / Real + - `EUR-BRL` — Euro / Real + - `GBP-BRL` — Libra Esterlina / Real + - `ARS-BRL` — Peso Argentino / Real + - `EUR-USD` — Euro / Dólar + - `BTC-BRL` — Bitcoin / Real + - `ETH-BRL` — Ethereum / Real - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + ### Campos da Resposta: - **Formas de Envio:** + - `fromCurrency` / `toCurrency` — Par de moedas + - `name` — Nome do par + - `bidPrice` — Preço de compra + - `askPrice` — Preço de venda + - `high` / `low` — Máxima/Mínima do dia + - `bidVariation` — Variação do preço de compra + - `percentageChange` — Variação percentual (%) - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + ### Fonte dos Dados: - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + Banco Central do Brasil (PTAX) / Yahoo Finance + + **Plano Mínimo:** Startup **Autenticação:** Necessária + + Args: + currency: Par(es) de moedas separados por vírgula (ex: USD-BRL,EUR-BRL) extra_headers: Send extra headers @@ -114,13 +124,7 @@ def retrieve( extra_query=extra_query, extra_body=extra_body, timeout=timeout, - query=maybe_transform( - { - "currency": currency, - "token": token, - }, - currency_retrieve_params.CurrencyRetrieveParams, - ), + query=maybe_transform({"currency": currency}, currency_retrieve_params.CurrencyRetrieveParams), ), cast_to=CurrencyRetrieveResponse, ) @@ -128,7 +132,6 @@ def retrieve( def list_available( self, *, - token: str | Omit = omit, search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. @@ -138,55 +141,32 @@ def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CurrencyListAvailableResponse: """ - Obtenha a lista completa de todas as moedas fiduciárias suportadas pela API, - geralmente utilizadas no parâmetro `currency` de outros endpoints (como o de - criptomoedas) ou para futuras funcionalidades de conversão. + Retorna a lista de pares de moedas disponíveis para consulta no endpoint + `/api/v2/currency`. - ### Funcionalidade: + ### Formato: - - Retorna um array `currencies` com os nomes das moedas. - - Pode ser filtrado usando o parâmetro `search`. + ORIGEM-DESTINO, onde ORIGEM é o código da moeda de origem e DESTINO a moeda de + destino - ### Autenticação: + ### Pares Disponíveis: - Requer token de autenticação via `token` (query) ou `Authorization` (header). + - **Moedas Fiduciárias:** USD-BRL, EUR-BRL, GBP-BRL, ARS-BRL, CAD-BRL, AUD-BRL, + JPY-BRL, CNY-BRL + - **Cross Rates:** EUR-USD, GBP-USD + - **Criptomoedas:** BTC-BRL, ETH-BRL - ### Exemplo de Requisição: - - **Listar todas as moedas disponíveis:** - - ```bash - curl -X GET "https://brapi.dev/api/v2/currency/available?token=SEU_TOKEN" - ``` - - **Buscar moedas cujo nome contenha 'Euro':** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/v2/currency/available?search=Euro&token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available?search=USD" ``` - ### Resposta: - - A resposta é um objeto JSON com a chave `currencies`, contendo um array de - objetos. Cada objeto possui uma chave `currency` com o nome completo da moeda - (ex: `"Dólar Americano/Real Brasileiro"`). **Nota:** O formato do nome pode - indicar um par de moedas, dependendo do contexto interno da API. + **Plano Mínimo:** Startup **Autenticação:** Necessária Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - search: **Opcional.** Termo para filtrar a lista pelo nome da moeda (correspondência - parcial, case-insensitive). + search: Filtrar pares de moedas por nome ou descrição extra_headers: Send extra headers @@ -203,19 +183,17 @@ def list_available( extra_query=extra_query, extra_body=extra_body, timeout=timeout, - query=maybe_transform( - { - "token": token, - "search": search, - }, - currency_list_available_params.CurrencyListAvailableParams, - ), + query=maybe_transform({"search": search}, currency_list_available_params.CurrencyListAvailableParams), ), cast_to=CurrencyListAvailableResponse, ) class AsyncCurrencyResource(AsyncAPIResource): + """ + Monitore taxas de câmbio entre moedas fiduciárias de todo o mundo, com atualizações frequentes e dados históricos. + """ + @cached_property def with_raw_response(self) -> AsyncCurrencyResourceWithRawResponse: """ @@ -238,8 +216,7 @@ def with_streaming_response(self) -> AsyncCurrencyResourceWithStreamingResponse: async def retrieve( self, *, - currency: str, - token: str | Omit = omit, + currency: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -248,49 +225,56 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CurrencyRetrieveResponse: """ - Obtenha cotações atualizadas para um ou mais pares de moedas fiduciárias (ex: - USD-BRL, EUR-USD). + Retorna cotações atualizadas de pares de moedas, com preço de compra/venda, + variação e extremos do dia. ### Funcionalidades: - - **Cotação Múltipla:** Consulte vários pares de moedas em uma única requisição - usando o parâmetro `currency`. - - **Dados Retornados:** Inclui nome do par, preços de compra (bid) e venda - (ask), variação, máximas e mínimas, e timestamp da atualização. + - **Cotação Atual:** Preço de compra (bid), venda (ask), máxima, mínima, + variação + - **Múltiplos Pares:** Consulte vários em uma requisição (separados por vírgula) + - **Formato:** `ORIGEM-DESTINO` (ex: `USD-BRL`) - ### Parâmetros: + ### Autenticação: - - **`currency` (Obrigatório):** Uma lista de pares de moedas separados por - vírgula, no formato `MOEDA_ORIGEM-MOEDA_DESTINO` (ex: `USD-BRL`, `EUR-USD`). - Consulte os pares disponíveis em - [`/api/v2/currency/available`](#/Moedas/getAvailableCurrencies). - - **`token` (Obrigatório):** Seu token de autenticação. + Bearer token ou query param `token`. Obtenha em brapi.dev/dashboard. - ### Autenticação: + ### Exemplos de Requisição: - Requer token de autenticação válido via `token` (query) ou `Authorization` - (header). + ```bash + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=USD-BRL" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=USD-BRL,EUR-BRL,GBP-BRL" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=BTC-BRL" + ``` - Args: - currency: **Obrigatório.** Uma lista de um ou mais pares de moedas a serem consultados, - separados por vírgula (`,`). + ### Pares de Moedas Populares: + + - `USD-BRL` — Dólar Americano / Real + - `EUR-BRL` — Euro / Real + - `GBP-BRL` — Libra Esterlina / Real + - `ARS-BRL` — Peso Argentino / Real + - `EUR-USD` — Euro / Dólar + - `BTC-BRL` — Bitcoin / Real + - `ETH-BRL` — Ethereum / Real - - **Formato:** `MOEDA_ORIGEM-MOEDA_DESTINO` (ex: `USD-BRL`). - - **Disponibilidade:** Consulte os pares válidos usando o endpoint - [`/api/v2/currency/available`](#/Moedas/getAvailableCurrencies). - - **Exemplo:** `USD-BRL,EUR-BRL,BTC-BRL` + ### Campos da Resposta: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + - `fromCurrency` / `toCurrency` — Par de moedas + - `name` — Nome do par + - `bidPrice` — Preço de compra + - `askPrice` — Preço de venda + - `high` / `low` — Máxima/Mínima do dia + - `bidVariation` — Variação do preço de compra + - `percentageChange` — Variação percentual (%) - **Formas de Envio:** + ### Fonte dos Dados: - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + Banco Central do Brasil (PTAX) / Yahoo Finance - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + **Plano Mínimo:** Startup **Autenticação:** Necessária + + Args: + currency: Par(es) de moedas separados por vírgula (ex: USD-BRL,EUR-BRL) extra_headers: Send extra headers @@ -308,11 +292,7 @@ async def retrieve( extra_body=extra_body, timeout=timeout, query=await async_maybe_transform( - { - "currency": currency, - "token": token, - }, - currency_retrieve_params.CurrencyRetrieveParams, + {"currency": currency}, currency_retrieve_params.CurrencyRetrieveParams ), ), cast_to=CurrencyRetrieveResponse, @@ -321,7 +301,6 @@ async def retrieve( async def list_available( self, *, - token: str | Omit = omit, search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. @@ -331,55 +310,32 @@ async def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CurrencyListAvailableResponse: """ - Obtenha a lista completa de todas as moedas fiduciárias suportadas pela API, - geralmente utilizadas no parâmetro `currency` de outros endpoints (como o de - criptomoedas) ou para futuras funcionalidades de conversão. + Retorna a lista de pares de moedas disponíveis para consulta no endpoint + `/api/v2/currency`. - ### Funcionalidade: + ### Formato: - - Retorna um array `currencies` com os nomes das moedas. - - Pode ser filtrado usando o parâmetro `search`. + ORIGEM-DESTINO, onde ORIGEM é o código da moeda de origem e DESTINO a moeda de + destino - ### Autenticação: + ### Pares Disponíveis: - Requer token de autenticação via `token` (query) ou `Authorization` (header). + - **Moedas Fiduciárias:** USD-BRL, EUR-BRL, GBP-BRL, ARS-BRL, CAD-BRL, AUD-BRL, + JPY-BRL, CNY-BRL + - **Cross Rates:** EUR-USD, GBP-USD + - **Criptomoedas:** BTC-BRL, ETH-BRL - ### Exemplo de Requisição: - - **Listar todas as moedas disponíveis:** - - ```bash - curl -X GET "https://brapi.dev/api/v2/currency/available?token=SEU_TOKEN" - ``` - - **Buscar moedas cujo nome contenha 'Euro':** + ### Exemplos de Requisição: ```bash - curl -X GET "https://brapi.dev/api/v2/currency/available?search=Euro&token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available?search=USD" ``` - ### Resposta: - - A resposta é um objeto JSON com a chave `currencies`, contendo um array de - objetos. Cada objeto possui uma chave `currency` com o nome completo da moeda - (ex: `"Dólar Americano/Real Brasileiro"`). **Nota:** O formato do nome pode - indicar um par de moedas, dependendo do contexto interno da API. + **Plano Mínimo:** Startup **Autenticação:** Necessária Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - search: **Opcional.** Termo para filtrar a lista pelo nome da moeda (correspondência - parcial, case-insensitive). + search: Filtrar pares de moedas por nome ou descrição extra_headers: Send extra headers @@ -397,11 +353,7 @@ async def list_available( extra_body=extra_body, timeout=timeout, query=await async_maybe_transform( - { - "token": token, - "search": search, - }, - currency_list_available_params.CurrencyListAvailableParams, + {"search": search}, currency_list_available_params.CurrencyListAvailableParams ), ), cast_to=CurrencyListAvailableResponse, diff --git a/src/brapi/resources/v2/inflation.py b/src/brapi/resources/v2/inflation.py index 7098b22..1119ec2 100644 --- a/src/brapi/resources/v2/inflation.py +++ b/src/brapi/resources/v2/inflation.py @@ -2,16 +2,12 @@ from __future__ import annotations -from typing import Union -from datetime import date -from typing_extensions import Literal - import httpx from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given from ..._utils import maybe_transform, async_maybe_transform from ..._compat import cached_property -from ...types.v2 import inflation_retrieve_params, inflation_list_available_params +from ...types.v2 import inflation_retrieve_params from ..._resource import SyncAPIResource, AsyncAPIResource from ..._response import ( to_raw_response_wrapper, @@ -27,6 +23,10 @@ class InflationResource(SyncAPIResource): + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ + @cached_property def with_raw_response(self) -> InflationResourceWithRawResponse: """ @@ -49,13 +49,11 @@ def with_streaming_response(self) -> InflationResourceWithStreamingResponse: def retrieve( self, *, - token: str | Omit = omit, - country: str | Omit = omit, - end: Union[str, date] | Omit = omit, - historical: bool | Omit = omit, - sort_by: Literal["date", "value"] | Omit = omit, - sort_order: Literal["asc", "desc"] | Omit = omit, - start: Union[str, date] | Omit = omit, + end: str | Omit = omit, + historical: str | Omit = omit, + sort_by: str | Omit = omit, + sort_order: str | Omit = omit, + start: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -64,77 +62,71 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> InflationRetrieveResponse: """ - Obtenha dados históricos sobre índices de inflação para um país específico. - - ### Funcionalidades: + Retorna dados históricos do **IPCA (Índice Nacional de Preços ao Consumidor + Amplo)**, o índice oficial de inflação do Brasil, medido pelo IBGE. - - **Seleção de País:** Especifique o país desejado com o parâmetro `country` - (padrão: `brazil`). - - **Filtragem por Período:** Defina um intervalo de datas com `start` e `end` - (formato DD/MM/YYYY). - - **Inclusão de Histórico:** O parâmetro `historical` (booleano) parece - controlar a inclusão de dados históricos (verificar comportamento exato, pode - ser redundante com `start`/`end`). - - **Ordenação:** Ordene os resultados por data (`date`) ou valor (`value`) - usando `sortBy` e `sortOrder`. + ### Funcionalidades - ### Autenticação: + - **Dados Mensais:** Variação percentual mensal do IPCA + - **Histórico Completo:** Dados desde janeiro/2000 até o mês atual + - **Filtros de Período:** Use `start` e `end` para definir período específico + (formato DD/MM/YYYY) + - **Ordenação:** Ordene por data ou valor, crescente ou decrescente - Requer token de autenticação via `token` (query) ou `Authorization` (header). + ### Autenticação - ### Exemplo de Requisição: + Bearer token ou query param `token`. Requer plano Startup. - **Buscar dados de inflação do Brasil para o ano de 2022, ordenados por valor - ascendente:** + ### Exemplos de Uso ```bash - curl -X GET "https://brapi.dev/api/v2/inflation?country=brazil&start=01/01/2022&end=31/12/2022&sortBy=value&sortOrder=asc&token=SEU_TOKEN" - ``` + # Padrão (últimos 12 meses) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation" - **Buscar os dados mais recentes de inflação (sem período definido, ordenação - padrão):** + # Histórico completo + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?historical=true" - ```bash - curl -X GET "https://brapi.dev/api/v2/inflation?country=brazil&token=SEU_TOKEN" + # Período específico + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?start=01/01/2023&end=31/12/2023" + + # Ordenado por valor (decrescente) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?historical=true&sortBy=value&sortOrder=desc" ``` - ### Resposta: + ### Parâmetros de Ordenação - A resposta contém um array `inflation`, onde cada objeto representa um ponto de - dado de inflação com sua `date` (DD/MM/YYYY), `value` (o índice de inflação como - string) e `epochDate` (timestamp UNIX). + - `sortBy`: `date` (padrão) ou `value` + - `sortOrder`: `desc` (padrão) ou `asc` - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + ### Campos da Resposta + + - `date` — Data no formato DD/MM/YYYY + - `value` — Variação percentual do IPCA no mês + - `epochDate` — Data em timestamp Unix (milissegundos) - **Formas de Envio:** + ### Sobre o IPCA - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + O IPCA é o índice oficial de inflação do Brasil, calculado mensalmente pelo + IBGE. Ele mede a variação de preços de uma cesta de produtos e serviços + consumidos pelas famílias brasileiras. - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + ### Fonte dos Dados - country: **Opcional.** Nome do país para o qual buscar os dados de inflação. Use nomes em - minúsculas. O padrão é `brazil`. Consulte `/api/v2/inflation/available` para a - lista de países suportados. + Banco Central do Brasil (BCB) — Série temporal 13522 do Sistema Gerador de + Séries Temporais (SGS) - end: **Opcional.** Data final do período desejado para os dados históricos, no - formato `DD/MM/YYYY`. Requerido se `start` for especificado. + **Plano Mínimo:** Startup | **Autenticação:** Necessária + + Args: + end: Data de fim (DD/MM/YYYY) - historical: **Opcional.** Booleano (`true` ou `false`). Define se dados históricos devem ser - incluídos. O comportamento exato em conjunto com `start`/`end` deve ser - verificado. Padrão: `false`. + historical: Incluir dados históricos (true/false) - sort_by: **Opcional.** Campo pelo qual os resultados da inflação serão ordenados. + sort_by: Campo para ordenação (date ou value) - sort_order: **Opcional.** Direção da ordenação: `asc` (ascendente) ou `desc` (descendente). - Padrão: `desc`. Requer que `sortBy` seja especificado. + sort_order: Ordem de classificação (asc ou desc) - start: **Opcional.** Data de início do período desejado para os dados históricos, no - formato `DD/MM/YYYY`. Requerido se `end` for especificado. + start: Data de início (DD/MM/YYYY) extra_headers: Send extra headers @@ -153,8 +145,6 @@ def retrieve( timeout=timeout, query=maybe_transform( { - "token": token, - "country": country, "end": end, "historical": historical, "sort_by": sort_by, @@ -170,8 +160,6 @@ def retrieve( def list_available( self, *, - token: str | Omit = omit, - search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -180,81 +168,36 @@ def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> InflationListAvailableResponse: """ - Obtenha a lista completa de todos os países para os quais a API Brapi possui - dados de inflação disponíveis para consulta no endpoint `/api/v2/inflation`. + Retorna a lista de países disponíveis para consulta de dados de inflação. - ### Funcionalidade: + ### Países Disponíveis - - Retorna um array `countries` com os nomes dos países (em minúsculas). - - Pode ser filtrado usando o parâmetro `search`. + - **brazil** — Dados do IPCA (IBGE) - ### Autenticação: + Use o valor retornado como referência para futuras expansões do endpoint. - Requer token de autenticação via `token` (query) ou `Authorization` (header). - - ### Exemplo de Requisição: - - **Listar todos os países com dados de inflação:** - - ```bash - curl -X GET "https://brapi.dev/api/v2/inflation/available?token=SEU_TOKEN" - ``` - - **Buscar países cujo nome contenha 'arg':** + ### Exemplo de Uso ```bash - curl -X GET "https://brapi.dev/api/v2/inflation/available?search=arg&token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation/available" ``` - ### Resposta: - - A resposta é um objeto JSON com a chave `countries`, contendo um array de - strings com os nomes dos países (ex: `["brazil", "argentina", "usa"]`). - - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - search: **Opcional.** Termo para filtrar a lista pelo nome do país (correspondência - parcial, case-insensitive). Se omitido, retorna todos os países. - - extra_headers: Send extra headers - - extra_query: Add additional query parameters to the request - - extra_body: Add additional JSON properties to the request - - timeout: Override the client-level default timeout for this request, in seconds + **Plano Mínimo:** Startup | **Autenticação:** Necessária """ return self._get( "/api/v2/inflation/available", options=make_request_options( - extra_headers=extra_headers, - extra_query=extra_query, - extra_body=extra_body, - timeout=timeout, - query=maybe_transform( - { - "token": token, - "search": search, - }, - inflation_list_available_params.InflationListAvailableParams, - ), + extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=InflationListAvailableResponse, ) class AsyncInflationResource(AsyncAPIResource): + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ + @cached_property def with_raw_response(self) -> AsyncInflationResourceWithRawResponse: """ @@ -277,13 +220,11 @@ def with_streaming_response(self) -> AsyncInflationResourceWithStreamingResponse async def retrieve( self, *, - token: str | Omit = omit, - country: str | Omit = omit, - end: Union[str, date] | Omit = omit, - historical: bool | Omit = omit, - sort_by: Literal["date", "value"] | Omit = omit, - sort_order: Literal["asc", "desc"] | Omit = omit, - start: Union[str, date] | Omit = omit, + end: str | Omit = omit, + historical: str | Omit = omit, + sort_by: str | Omit = omit, + sort_order: str | Omit = omit, + start: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -292,77 +233,71 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> InflationRetrieveResponse: """ - Obtenha dados históricos sobre índices de inflação para um país específico. - - ### Funcionalidades: + Retorna dados históricos do **IPCA (Índice Nacional de Preços ao Consumidor + Amplo)**, o índice oficial de inflação do Brasil, medido pelo IBGE. - - **Seleção de País:** Especifique o país desejado com o parâmetro `country` - (padrão: `brazil`). - - **Filtragem por Período:** Defina um intervalo de datas com `start` e `end` - (formato DD/MM/YYYY). - - **Inclusão de Histórico:** O parâmetro `historical` (booleano) parece - controlar a inclusão de dados históricos (verificar comportamento exato, pode - ser redundante com `start`/`end`). - - **Ordenação:** Ordene os resultados por data (`date`) ou valor (`value`) - usando `sortBy` e `sortOrder`. + ### Funcionalidades - ### Autenticação: + - **Dados Mensais:** Variação percentual mensal do IPCA + - **Histórico Completo:** Dados desde janeiro/2000 até o mês atual + - **Filtros de Período:** Use `start` e `end` para definir período específico + (formato DD/MM/YYYY) + - **Ordenação:** Ordene por data ou valor, crescente ou decrescente - Requer token de autenticação via `token` (query) ou `Authorization` (header). + ### Autenticação - ### Exemplo de Requisição: + Bearer token ou query param `token`. Requer plano Startup. - **Buscar dados de inflação do Brasil para o ano de 2022, ordenados por valor - ascendente:** + ### Exemplos de Uso ```bash - curl -X GET "https://brapi.dev/api/v2/inflation?country=brazil&start=01/01/2022&end=31/12/2022&sortBy=value&sortOrder=asc&token=SEU_TOKEN" - ``` + # Padrão (últimos 12 meses) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation" - **Buscar os dados mais recentes de inflação (sem período definido, ordenação - padrão):** + # Histórico completo + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?historical=true" - ```bash - curl -X GET "https://brapi.dev/api/v2/inflation?country=brazil&token=SEU_TOKEN" + # Período específico + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?start=01/01/2023&end=31/12/2023" + + # Ordenado por valor (decrescente) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?historical=true&sortBy=value&sortOrder=desc" ``` - ### Resposta: + ### Parâmetros de Ordenação - A resposta contém um array `inflation`, onde cada objeto representa um ponto de - dado de inflação com sua `date` (DD/MM/YYYY), `value` (o índice de inflação como - string) e `epochDate` (timestamp UNIX). + - `sortBy`: `date` (padrão) ou `value` + - `sortOrder`: `desc` (padrão) ou `asc` - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + ### Campos da Resposta + + - `date` — Data no formato DD/MM/YYYY + - `value` — Variação percentual do IPCA no mês + - `epochDate` — Data em timestamp Unix (milissegundos) - **Formas de Envio:** + ### Sobre o IPCA - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + O IPCA é o índice oficial de inflação do Brasil, calculado mensalmente pelo + IBGE. Ele mede a variação de preços de uma cesta de produtos e serviços + consumidos pelas famílias brasileiras. - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + ### Fonte dos Dados - country: **Opcional.** Nome do país para o qual buscar os dados de inflação. Use nomes em - minúsculas. O padrão é `brazil`. Consulte `/api/v2/inflation/available` para a - lista de países suportados. + Banco Central do Brasil (BCB) — Série temporal 13522 do Sistema Gerador de + Séries Temporais (SGS) - end: **Opcional.** Data final do período desejado para os dados históricos, no - formato `DD/MM/YYYY`. Requerido se `start` for especificado. + **Plano Mínimo:** Startup | **Autenticação:** Necessária - historical: **Opcional.** Booleano (`true` ou `false`). Define se dados históricos devem ser - incluídos. O comportamento exato em conjunto com `start`/`end` deve ser - verificado. Padrão: `false`. + Args: + end: Data de fim (DD/MM/YYYY) - sort_by: **Opcional.** Campo pelo qual os resultados da inflação serão ordenados. + historical: Incluir dados históricos (true/false) - sort_order: **Opcional.** Direção da ordenação: `asc` (ascendente) ou `desc` (descendente). - Padrão: `desc`. Requer que `sortBy` seja especificado. + sort_by: Campo para ordenação (date ou value) - start: **Opcional.** Data de início do período desejado para os dados históricos, no - formato `DD/MM/YYYY`. Requerido se `end` for especificado. + sort_order: Ordem de classificação (asc ou desc) + + start: Data de início (DD/MM/YYYY) extra_headers: Send extra headers @@ -381,8 +316,6 @@ async def retrieve( timeout=timeout, query=await async_maybe_transform( { - "token": token, - "country": country, "end": end, "historical": historical, "sort_by": sort_by, @@ -398,8 +331,6 @@ async def retrieve( async def list_available( self, *, - token: str | Omit = omit, - search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -408,75 +339,26 @@ async def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> InflationListAvailableResponse: """ - Obtenha a lista completa de todos os países para os quais a API Brapi possui - dados de inflação disponíveis para consulta no endpoint `/api/v2/inflation`. - - ### Funcionalidade: + Retorna a lista de países disponíveis para consulta de dados de inflação. - - Retorna um array `countries` com os nomes dos países (em minúsculas). - - Pode ser filtrado usando o parâmetro `search`. + ### Países Disponíveis - ### Autenticação: + - **brazil** — Dados do IPCA (IBGE) - Requer token de autenticação via `token` (query) ou `Authorization` (header). + Use o valor retornado como referência para futuras expansões do endpoint. - ### Exemplo de Requisição: - - **Listar todos os países com dados de inflação:** - - ```bash - curl -X GET "https://brapi.dev/api/v2/inflation/available?token=SEU_TOKEN" - ``` - - **Buscar países cujo nome contenha 'arg':** + ### Exemplo de Uso ```bash - curl -X GET "https://brapi.dev/api/v2/inflation/available?search=arg&token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation/available" ``` - ### Resposta: - - A resposta é um objeto JSON com a chave `countries`, contendo um array de - strings com os nomes dos países (ex: `["brazil", "argentina", "usa"]`). - - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - search: **Opcional.** Termo para filtrar a lista pelo nome do país (correspondência - parcial, case-insensitive). Se omitido, retorna todos os países. - - extra_headers: Send extra headers - - extra_query: Add additional query parameters to the request - - extra_body: Add additional JSON properties to the request - - timeout: Override the client-level default timeout for this request, in seconds + **Plano Mínimo:** Startup | **Autenticação:** Necessária """ return await self._get( "/api/v2/inflation/available", options=make_request_options( - extra_headers=extra_headers, - extra_query=extra_query, - extra_body=extra_body, - timeout=timeout, - query=await async_maybe_transform( - { - "token": token, - "search": search, - }, - inflation_list_available_params.InflationListAvailableParams, - ), + extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=InflationListAvailableResponse, ) diff --git a/src/brapi/resources/v2/prime_rate.py b/src/brapi/resources/v2/prime_rate.py index 0dedc9b..93dd28b 100644 --- a/src/brapi/resources/v2/prime_rate.py +++ b/src/brapi/resources/v2/prime_rate.py @@ -2,16 +2,12 @@ from __future__ import annotations -from typing import Union -from datetime import date -from typing_extensions import Literal - import httpx from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given from ..._utils import maybe_transform, async_maybe_transform from ..._compat import cached_property -from ...types.v2 import prime_rate_retrieve_params, prime_rate_list_available_params +from ...types.v2 import prime_rate_retrieve_params from ..._resource import SyncAPIResource, AsyncAPIResource from ..._response import ( to_raw_response_wrapper, @@ -27,6 +23,10 @@ class PrimeRateResource(SyncAPIResource): + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ + @cached_property def with_raw_response(self) -> PrimeRateResourceWithRawResponse: """ @@ -49,13 +49,11 @@ def with_streaming_response(self) -> PrimeRateResourceWithStreamingResponse: def retrieve( self, *, - token: str | Omit = omit, - country: str | Omit = omit, - end: Union[str, date] | Omit = omit, - historical: bool | Omit = omit, - sort_by: Literal["date", "value"] | Omit = omit, - sort_order: Literal["asc", "desc"] | Omit = omit, - start: Union[str, date] | Omit = omit, + end: str | Omit = omit, + historical: str | Omit = omit, + sort_by: str | Omit = omit, + sort_order: str | Omit = omit, + start: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -64,65 +62,72 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> PrimeRateRetrieveResponse: """ - Obtenha informações atualizadas sobre a taxa básica de juros (SELIC) de um país - por um período determinado. - - ### Funcionalidades: + Retorna dados históricos da **Taxa SELIC (Sistema Especial de Liquidação e de + Custódia)**, a taxa básica de juros da economia brasileira, definida pelo COPOM + (Comitê de Política Monetária) do Banco Central. - - **Seleção por País:** Especifique o país desejado usando o parâmetro `country` - (padrão: brazil). - - **Período Customizado:** Defina datas de início e fim com `start` e `end` para - consultar um intervalo específico. - - **Ordenação:** Ordene os resultados por data ou valor com os parâmetros - `sortBy` e `sortOrder`. - - **Dados Históricos:** Solicite o histórico completo ou apenas o valor mais - recente com o parâmetro `historical`. + ### Funcionalidades - ### Autenticação: + - **Dados Diários:** Taxa SELIC diária (meta anualizada, % a.a.) + - **Histórico Completo:** Dados desde janeiro/2000 até a data atual + - **Filtros de Período:** Use `start` e `end` (formato DD/MM/YYYY) + - **Ordenação:** Por data ou valor, crescente ou decrescente - Requer token de autenticação via `token` (query) ou `Authorization` (header). + ### Autenticação - ### Exemplo de Requisição: + Bearer token ou query param `token`. Requer plano Startup. - **Taxa de juros do Brasil entre dezembro/2021 e janeiro/2022:** + ### Exemplos de Uso ```bash - curl -X GET "https://brapi.dev/api/v2/prime-rate?country=brazil&start=01/12/2021&end=01/01/2022&sortBy=date&sortOrder=desc&token=SEU_TOKEN" + # Padrão (últimos 12 meses) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate" + + # Histórico completo + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?historical=true" + + # Período específico + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?start=01/01/2023&end=31/12/2023" + + # Ordenado por valor (decrescente) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?historical=true&sortBy=value&sortOrder=desc" ``` - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + ### Parâmetros de Ordenação + + - `sortBy`: `date` (padrão) ou `value` + - `sortOrder`: `desc` (padrão) ou `asc` + + ### Campos da Resposta - **Formas de Envio:** + - `date` — Data no formato DD/MM/YYYY + - `value` — Taxa SELIC meta anualizada (% a.a.) + - `epochDate` — Data em timestamp Unix (milissegundos) - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + ### Sobre a SELIC - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + A SELIC é a taxa básica de juros da economia brasileira e influencia todas as + demais taxas de juros do país (empréstimos, financiamentos, aplicações + financeiras). Ela é definida pelo COPOM a cada 45 dias e serve como referência + para o CDI. - country: **Opcional.** O país do qual você deseja obter informações sobre a taxa básica - de juros. Por padrão, o país é definido como brazil. Você pode consultar a lista - de países disponíveis através do endpoint `/api/v2/prime-rate/available`. + ### Fonte dos Dados - end: **Opcional.** Data final do período para busca no formato DD/MM/YYYY. Por padrão - é a data atual. Útil quando `historical=true` para restringir o período da série - histórica. + Banco Central do Brasil (BCB) — Série temporal 432 do Sistema Gerador de Séries + Temporais (SGS) - historical: **Opcional.** Define se os dados históricos serão retornados. Se definido como - `true`, retorna a série histórica completa. Se `false` (padrão) ou omitido, - retorna apenas o valor mais recente. + **Plano Mínimo:** Startup | **Autenticação:** Necessária - sort_by: **Opcional.** Campo pelo qual os resultados serão ordenados. Por padrão, ordena - por `date` (data). + Args: + end: Data de fim (DD/MM/YYYY) + + historical: Incluir dados históricos (true/false) + + sort_by: Campo para ordenação (date ou value) - sort_order: **Opcional.** Define se a ordenação será crescente (`asc`) ou decrescente - (`desc`). Por padrão, é `desc` (decrescente). + sort_order: Ordem de classificação (asc ou desc) - start: **Opcional.** Data inicial do período para busca no formato DD/MM/YYYY. Útil - quando `historical=true` para restringir o período da série histórica. + start: Data de início (DD/MM/YYYY) extra_headers: Send extra headers @@ -141,8 +146,6 @@ def retrieve( timeout=timeout, query=maybe_transform( { - "token": token, - "country": country, "end": end, "historical": historical, "sort_by": sort_by, @@ -158,8 +161,6 @@ def retrieve( def list_available( self, *, - token: str | Omit = omit, - search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -168,73 +169,36 @@ def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> PrimeRateListAvailableResponse: """ - Liste todos os países disponíveis com dados de taxa básica de juros (SELIC) na - API brapi. Este endpoint facilita a descoberta de quais países possuem dados - disponíveis para consulta através do endpoint principal `/api/v2/prime-rate`. - - ### Funcionalidades: - - - **Busca Filtrada:** Utilize o parâmetro `search` para filtrar países por nome - ou parte do nome. - - **Ideal para Autocomplete:** Perfeito para implementar campos de busca com - autocompletar em interfaces de usuário. + Retorna a lista de países disponíveis para consulta de dados de taxa de juros. - ### Autenticação: + ### Países Disponíveis - Requer token de autenticação via `token` (query) ou `Authorization` (header). + - **brazil** — Taxa SELIC (Banco Central) - ### Exemplo de Requisição: + Use o valor retornado como referência para futuras expansões do endpoint. - **Listar países que contenham "BR" no nome:** + ### Exemplo de Uso ```bash - curl -X GET "https://brapi.dev/api/v2/prime-rate/available?search=BR&token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate/available" ``` - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - search: **Opcional.** Termo para filtrar a lista de países por nome. Retorna países - cujos nomes contenham o termo especificado (case insensitive). - - extra_headers: Send extra headers - - extra_query: Add additional query parameters to the request - - extra_body: Add additional JSON properties to the request - - timeout: Override the client-level default timeout for this request, in seconds + **Plano Mínimo:** Startup | **Autenticação:** Necessária """ return self._get( "/api/v2/prime-rate/available", options=make_request_options( - extra_headers=extra_headers, - extra_query=extra_query, - extra_body=extra_body, - timeout=timeout, - query=maybe_transform( - { - "token": token, - "search": search, - }, - prime_rate_list_available_params.PrimeRateListAvailableParams, - ), + extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=PrimeRateListAvailableResponse, ) class AsyncPrimeRateResource(AsyncAPIResource): + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ + @cached_property def with_raw_response(self) -> AsyncPrimeRateResourceWithRawResponse: """ @@ -257,13 +221,11 @@ def with_streaming_response(self) -> AsyncPrimeRateResourceWithStreamingResponse async def retrieve( self, *, - token: str | Omit = omit, - country: str | Omit = omit, - end: Union[str, date] | Omit = omit, - historical: bool | Omit = omit, - sort_by: Literal["date", "value"] | Omit = omit, - sort_order: Literal["asc", "desc"] | Omit = omit, - start: Union[str, date] | Omit = omit, + end: str | Omit = omit, + historical: str | Omit = omit, + sort_by: str | Omit = omit, + sort_order: str | Omit = omit, + start: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -272,65 +234,72 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> PrimeRateRetrieveResponse: """ - Obtenha informações atualizadas sobre a taxa básica de juros (SELIC) de um país - por um período determinado. - - ### Funcionalidades: + Retorna dados históricos da **Taxa SELIC (Sistema Especial de Liquidação e de + Custódia)**, a taxa básica de juros da economia brasileira, definida pelo COPOM + (Comitê de Política Monetária) do Banco Central. - - **Seleção por País:** Especifique o país desejado usando o parâmetro `country` - (padrão: brazil). - - **Período Customizado:** Defina datas de início e fim com `start` e `end` para - consultar um intervalo específico. - - **Ordenação:** Ordene os resultados por data ou valor com os parâmetros - `sortBy` e `sortOrder`. - - **Dados Históricos:** Solicite o histórico completo ou apenas o valor mais - recente com o parâmetro `historical`. + ### Funcionalidades - ### Autenticação: + - **Dados Diários:** Taxa SELIC diária (meta anualizada, % a.a.) + - **Histórico Completo:** Dados desde janeiro/2000 até a data atual + - **Filtros de Período:** Use `start` e `end` (formato DD/MM/YYYY) + - **Ordenação:** Por data ou valor, crescente ou decrescente - Requer token de autenticação via `token` (query) ou `Authorization` (header). + ### Autenticação - ### Exemplo de Requisição: + Bearer token ou query param `token`. Requer plano Startup. - **Taxa de juros do Brasil entre dezembro/2021 e janeiro/2022:** + ### Exemplos de Uso ```bash - curl -X GET "https://brapi.dev/api/v2/prime-rate?country=brazil&start=01/12/2021&end=01/01/2022&sortBy=date&sortOrder=desc&token=SEU_TOKEN" + # Padrão (últimos 12 meses) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate" + + # Histórico completo + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?historical=true" + + # Período específico + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?start=01/01/2023&end=31/12/2023" + + # Ordenado por valor (decrescente) + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?historical=true&sortBy=value&sortOrder=desc" ``` - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + ### Parâmetros de Ordenação + + - `sortBy`: `date` (padrão) ou `value` + - `sortOrder`: `desc` (padrão) ou `asc` - **Formas de Envio:** + ### Campos da Resposta - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + - `date` — Data no formato DD/MM/YYYY + - `value` — Taxa SELIC meta anualizada (% a.a.) + - `epochDate` — Data em timestamp Unix (milissegundos) - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). + ### Sobre a SELIC - country: **Opcional.** O país do qual você deseja obter informações sobre a taxa básica - de juros. Por padrão, o país é definido como brazil. Você pode consultar a lista - de países disponíveis através do endpoint `/api/v2/prime-rate/available`. + A SELIC é a taxa básica de juros da economia brasileira e influencia todas as + demais taxas de juros do país (empréstimos, financiamentos, aplicações + financeiras). Ela é definida pelo COPOM a cada 45 dias e serve como referência + para o CDI. - end: **Opcional.** Data final do período para busca no formato DD/MM/YYYY. Por padrão - é a data atual. Útil quando `historical=true` para restringir o período da série - histórica. + ### Fonte dos Dados - historical: **Opcional.** Define se os dados históricos serão retornados. Se definido como - `true`, retorna a série histórica completa. Se `false` (padrão) ou omitido, - retorna apenas o valor mais recente. + Banco Central do Brasil (BCB) — Série temporal 432 do Sistema Gerador de Séries + Temporais (SGS) - sort_by: **Opcional.** Campo pelo qual os resultados serão ordenados. Por padrão, ordena - por `date` (data). + **Plano Mínimo:** Startup | **Autenticação:** Necessária + + Args: + end: Data de fim (DD/MM/YYYY) - sort_order: **Opcional.** Define se a ordenação será crescente (`asc`) ou decrescente - (`desc`). Por padrão, é `desc` (decrescente). + historical: Incluir dados históricos (true/false) - start: **Opcional.** Data inicial do período para busca no formato DD/MM/YYYY. Útil - quando `historical=true` para restringir o período da série histórica. + sort_by: Campo para ordenação (date ou value) + + sort_order: Ordem de classificação (asc ou desc) + + start: Data de início (DD/MM/YYYY) extra_headers: Send extra headers @@ -349,8 +318,6 @@ async def retrieve( timeout=timeout, query=await async_maybe_transform( { - "token": token, - "country": country, "end": end, "historical": historical, "sort_by": sort_by, @@ -366,8 +333,6 @@ async def retrieve( async def list_available( self, *, - token: str | Omit = omit, - search: str | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -376,67 +341,26 @@ async def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> PrimeRateListAvailableResponse: """ - Liste todos os países disponíveis com dados de taxa básica de juros (SELIC) na - API brapi. Este endpoint facilita a descoberta de quais países possuem dados - disponíveis para consulta através do endpoint principal `/api/v2/prime-rate`. - - ### Funcionalidades: - - - **Busca Filtrada:** Utilize o parâmetro `search` para filtrar países por nome - ou parte do nome. - - **Ideal para Autocomplete:** Perfeito para implementar campos de busca com - autocompletar em interfaces de usuário. + Retorna a lista de países disponíveis para consulta de dados de taxa de juros. - ### Autenticação: + ### Países Disponíveis - Requer token de autenticação via `token` (query) ou `Authorization` (header). + - **brazil** — Taxa SELIC (Banco Central) - ### Exemplo de Requisição: + Use o valor retornado como referência para futuras expansões do endpoint. - **Listar países que contenham "BR" no nome:** + ### Exemplo de Uso ```bash - curl -X GET "https://brapi.dev/api/v2/prime-rate/available?search=BR&token=SEU_TOKEN" + curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate/available" ``` - Args: - token: **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - - search: **Opcional.** Termo para filtrar a lista de países por nome. Retorna países - cujos nomes contenham o termo especificado (case insensitive). - - extra_headers: Send extra headers - - extra_query: Add additional query parameters to the request - - extra_body: Add additional JSON properties to the request - - timeout: Override the client-level default timeout for this request, in seconds + **Plano Mínimo:** Startup | **Autenticação:** Necessária """ return await self._get( "/api/v2/prime-rate/available", options=make_request_options( - extra_headers=extra_headers, - extra_query=extra_query, - extra_body=extra_body, - timeout=timeout, - query=await async_maybe_transform( - { - "token": token, - "search": search, - }, - prime_rate_list_available_params.PrimeRateListAvailableParams, - ), + extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout ), cast_to=PrimeRateListAvailableResponse, ) diff --git a/src/brapi/resources/v2/v2.py b/src/brapi/resources/v2/v2.py index 3fa73c9..896ddb7 100644 --- a/src/brapi/resources/v2/v2.py +++ b/src/brapi/resources/v2/v2.py @@ -43,18 +43,30 @@ class V2Resource(SyncAPIResource): @cached_property def crypto(self) -> CryptoResource: + """ + Obtenha cotações em tempo real e dados históricos de criptomoedas, disponíveis em diversas moedas de referência. + """ return CryptoResource(self._client) @cached_property def currency(self) -> CurrencyResource: + """ + Monitore taxas de câmbio entre moedas fiduciárias de todo o mundo, com atualizações frequentes e dados históricos. + """ return CurrencyResource(self._client) @cached_property def inflation(self) -> InflationResource: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return InflationResource(self._client) @cached_property def prime_rate(self) -> PrimeRateResource: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return PrimeRateResource(self._client) @cached_property @@ -80,18 +92,30 @@ def with_streaming_response(self) -> V2ResourceWithStreamingResponse: class AsyncV2Resource(AsyncAPIResource): @cached_property def crypto(self) -> AsyncCryptoResource: + """ + Obtenha cotações em tempo real e dados históricos de criptomoedas, disponíveis em diversas moedas de referência. + """ return AsyncCryptoResource(self._client) @cached_property def currency(self) -> AsyncCurrencyResource: + """ + Monitore taxas de câmbio entre moedas fiduciárias de todo o mundo, com atualizações frequentes e dados históricos. + """ return AsyncCurrencyResource(self._client) @cached_property def inflation(self) -> AsyncInflationResource: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return AsyncInflationResource(self._client) @cached_property def prime_rate(self) -> AsyncPrimeRateResource: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return AsyncPrimeRateResource(self._client) @cached_property @@ -120,18 +144,30 @@ def __init__(self, v2: V2Resource) -> None: @cached_property def crypto(self) -> CryptoResourceWithRawResponse: + """ + Obtenha cotações em tempo real e dados históricos de criptomoedas, disponíveis em diversas moedas de referência. + """ return CryptoResourceWithRawResponse(self._v2.crypto) @cached_property def currency(self) -> CurrencyResourceWithRawResponse: + """ + Monitore taxas de câmbio entre moedas fiduciárias de todo o mundo, com atualizações frequentes e dados históricos. + """ return CurrencyResourceWithRawResponse(self._v2.currency) @cached_property def inflation(self) -> InflationResourceWithRawResponse: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return InflationResourceWithRawResponse(self._v2.inflation) @cached_property def prime_rate(self) -> PrimeRateResourceWithRawResponse: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return PrimeRateResourceWithRawResponse(self._v2.prime_rate) @@ -141,18 +177,30 @@ def __init__(self, v2: AsyncV2Resource) -> None: @cached_property def crypto(self) -> AsyncCryptoResourceWithRawResponse: + """ + Obtenha cotações em tempo real e dados históricos de criptomoedas, disponíveis em diversas moedas de referência. + """ return AsyncCryptoResourceWithRawResponse(self._v2.crypto) @cached_property def currency(self) -> AsyncCurrencyResourceWithRawResponse: + """ + Monitore taxas de câmbio entre moedas fiduciárias de todo o mundo, com atualizações frequentes e dados históricos. + """ return AsyncCurrencyResourceWithRawResponse(self._v2.currency) @cached_property def inflation(self) -> AsyncInflationResourceWithRawResponse: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return AsyncInflationResourceWithRawResponse(self._v2.inflation) @cached_property def prime_rate(self) -> AsyncPrimeRateResourceWithRawResponse: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return AsyncPrimeRateResourceWithRawResponse(self._v2.prime_rate) @@ -162,18 +210,30 @@ def __init__(self, v2: V2Resource) -> None: @cached_property def crypto(self) -> CryptoResourceWithStreamingResponse: + """ + Obtenha cotações em tempo real e dados históricos de criptomoedas, disponíveis em diversas moedas de referência. + """ return CryptoResourceWithStreamingResponse(self._v2.crypto) @cached_property def currency(self) -> CurrencyResourceWithStreamingResponse: + """ + Monitore taxas de câmbio entre moedas fiduciárias de todo o mundo, com atualizações frequentes e dados históricos. + """ return CurrencyResourceWithStreamingResponse(self._v2.currency) @cached_property def inflation(self) -> InflationResourceWithStreamingResponse: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return InflationResourceWithStreamingResponse(self._v2.inflation) @cached_property def prime_rate(self) -> PrimeRateResourceWithStreamingResponse: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return PrimeRateResourceWithStreamingResponse(self._v2.prime_rate) @@ -183,16 +243,28 @@ def __init__(self, v2: AsyncV2Resource) -> None: @cached_property def crypto(self) -> AsyncCryptoResourceWithStreamingResponse: + """ + Obtenha cotações em tempo real e dados históricos de criptomoedas, disponíveis em diversas moedas de referência. + """ return AsyncCryptoResourceWithStreamingResponse(self._v2.crypto) @cached_property def currency(self) -> AsyncCurrencyResourceWithStreamingResponse: + """ + Monitore taxas de câmbio entre moedas fiduciárias de todo o mundo, com atualizações frequentes e dados históricos. + """ return AsyncCurrencyResourceWithStreamingResponse(self._v2.currency) @cached_property def inflation(self) -> AsyncInflationResourceWithStreamingResponse: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return AsyncInflationResourceWithStreamingResponse(self._v2.inflation) @cached_property def prime_rate(self) -> AsyncPrimeRateResourceWithStreamingResponse: + """ + Acompanhe os principais indicadores econômicos do Brasil, incluindo inflação (IPCA, IGP-M) e Taxa Selic. + """ return AsyncPrimeRateResourceWithStreamingResponse(self._v2.prime_rate) diff --git a/src/brapi/types/__init__.py b/src/brapi/types/__init__.py index 91dde6b..5752791 100644 --- a/src/brapi/types/__init__.py +++ b/src/brapi/types/__init__.py @@ -2,15 +2,11 @@ from __future__ import annotations -from .cashflow_entry import CashflowEntry as CashflowEntry from .quote_list_params import QuoteListParams as QuoteListParams -from .value_added_entry import ValueAddedEntry as ValueAddedEntry from .balance_sheet_entry import BalanceSheetEntry as BalanceSheetEntry from .quote_list_response import QuoteListResponse as QuoteListResponse from .financial_data_entry import FinancialDataEntry as FinancialDataEntry from .available_list_params import AvailableListParams as AvailableListParams from .quote_retrieve_params import QuoteRetrieveParams as QuoteRetrieveParams -from .income_statement_entry import IncomeStatementEntry as IncomeStatementEntry from .available_list_response import AvailableListResponse as AvailableListResponse from .quote_retrieve_response import QuoteRetrieveResponse as QuoteRetrieveResponse -from .default_key_statistics_entry import DefaultKeyStatisticsEntry as DefaultKeyStatisticsEntry diff --git a/src/brapi/types/available_list_params.py b/src/brapi/types/available_list_params.py index 631921d..e25d462 100644 --- a/src/brapi/types/available_list_params.py +++ b/src/brapi/types/available_list_params.py @@ -8,23 +8,5 @@ class AvailableListParams(TypedDict, total=False): - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ - search: str - """ - **Opcional.** Termo para filtrar a lista de tickers (correspondência parcial, - case-insensitive). Se omitido, retorna todos os tickers. - """ + """Filtrar ações e índices por nome ou código""" diff --git a/src/brapi/types/available_list_response.py b/src/brapi/types/available_list_response.py index 07e0719..08deefd 100644 --- a/src/brapi/types/available_list_response.py +++ b/src/brapi/types/available_list_response.py @@ -8,13 +8,8 @@ class AvailableListResponse(BaseModel): - """Resposta do endpoint que lista todos os tickers disponíveis.""" - indexes: List[str] - """Lista de tickers de **índices** disponíveis (ex: `^BVSP`, `^IFIX`).""" + """Lista de índices disponíveis""" stocks: List[str] - """ - Lista de tickers de **ações, FIIs, BDRs e ETFs** disponíveis (ex: `PETR4`, - `VALE3`, `MXRF11`). - """ + """Lista de códigos de ações disponíveis""" diff --git a/src/brapi/types/balance_sheet_entry.py b/src/brapi/types/balance_sheet_entry.py index 38a4aa7..de762a0 100644 --- a/src/brapi/types/balance_sheet_entry.py +++ b/src/brapi/types/balance_sheet_entry.py @@ -1,8 +1,6 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. from typing import Optional -from datetime import date -from typing_extensions import Literal from pydantic import Field as FieldInfo @@ -12,448 +10,62 @@ class BalanceSheetEntry(BaseModel): - """ - Representa os dados de um Balanço Patrimonial para um período específico (anual ou trimestral). - """ - accounts_payable: Optional[float] = FieldInfo(alias="accountsPayable", default=None) - """Contas a pagar (fornecedores).""" - - accounts_receivable_from_clients: Optional[float] = FieldInfo(alias="accountsReceivableFromClients", default=None) - """Contas a receber de clientes (bruto).""" - - accumulated_profits_or_losses: Optional[float] = FieldInfo(alias="accumulatedProfitsOrLosses", default=None) - """Lucros ou prejuízos acumulados.""" - - advance_for_future_capital_increase: Optional[float] = FieldInfo( - alias="advanceForFutureCapitalIncrease", default=None - ) - """Adiantamento para futuro aumento de capital (AFAC).""" - - biological_assets: Optional[float] = FieldInfo(alias="biologicalAssets", default=None) - """Ativos biológicos.""" - - capitalization: Optional[float] = None - """Obrigações de capitalização.""" - - capital_reserves: Optional[float] = FieldInfo(alias="capitalReserves", default=None) - """Reservas de capital (sinônimo de `capitalSurplus`).""" - - capital_surplus: Optional[float] = FieldInfo(alias="capitalSurplus", default=None) - """Reservas de capital.""" + """Fornecedores""" cash: Optional[float] = None - """Caixa e equivalentes de caixa.""" - - central_bank_compulsory_deposit: Optional[float] = FieldInfo(alias="centralBankCompulsoryDeposit", default=None) - """Depósitos compulsórios no Banco Central.""" - - common_stock: Optional[float] = FieldInfo(alias="commonStock", default=None) - """Capital social realizado.""" - - complementary_pension: Optional[float] = FieldInfo(alias="complementaryPension", default=None) - """Obrigações de previdência complementar.""" - - compulsory_loans_and_deposits: Optional[float] = FieldInfo(alias="compulsoryLoansAndDeposits", default=None) - """Empréstimos e depósitos compulsórios.""" - - controller_shareholders_equity: Optional[float] = FieldInfo(alias="controllerShareholdersEquity", default=None) - """Patrimônio líquido atribuível aos controladores.""" - - credits_from_operations: Optional[float] = FieldInfo(alias="creditsFromOperations", default=None) - """Créditos oriundos de operações (instituições financeiras/seguradoras).""" - - credits_with_related_parties: Optional[float] = FieldInfo(alias="creditsWithRelatedParties", default=None) - """Créditos com partes relacionadas.""" - - cumulative_conversion_adjustments: Optional[float] = FieldInfo( - alias="cumulativeConversionAdjustments", default=None - ) - """Ajustes acumulados de conversão.""" - - current_and_deferred_taxes: Optional[float] = FieldInfo(alias="currentAndDeferredTaxes", default=None) - """Tributos correntes e diferidos no ativo.""" - - current_liabilities: Optional[float] = FieldInfo(alias="currentLiabilities", default=None) - """Total do passivo circulante (sinônimo de `totalCurrentLiabilities`).""" - - debentures: Optional[float] = None - """Debêntures (passivo circulante).""" - - debits_from_capitalization: Optional[float] = FieldInfo(alias="debitsFromCapitalization", default=None) - """Débitos de operações de capitalização.""" - - debits_from_complementary_pension: Optional[float] = FieldInfo(alias="debitsFromComplementaryPension", default=None) - """Débitos de operações de previdência complementar.""" - - debits_from_insurance_and_reinsurance: Optional[float] = FieldInfo( - alias="debitsFromInsuranceAndReinsurance", default=None - ) - """Débitos de operações de seguros e resseguros.""" - - debits_from_operations: Optional[float] = FieldInfo(alias="debitsFromOperations", default=None) - """Débitos oriundos de operações.""" - - debits_from_other_operations: Optional[float] = FieldInfo(alias="debitsFromOtherOperations", default=None) - """Débitos de outras operações.""" - - deferred_long_term_asset_charges: Optional[float] = FieldInfo(alias="deferredLongTermAssetCharges", default=None) - """Encargos diferidos de ativos de longo prazo.""" - - deferred_long_term_liab: Optional[float] = FieldInfo(alias="deferredLongTermLiab", default=None) - """Passivos fiscais diferidos (longo prazo).""" - - deferred_selling_expenses: Optional[float] = FieldInfo(alias="deferredSellingExpenses", default=None) - """Despesas de comercialização diferidas.""" - - deferred_taxes: Optional[float] = FieldInfo(alias="deferredTaxes", default=None) - """Tributos diferidos no ativo.""" + """Caixa""" - end_date: Optional[date] = FieldInfo(alias="endDate", default=None) - """Data de término do período fiscal ao qual o balanço se refere (YYYY-MM-DD).""" - - equity_valuation_adjustments: Optional[float] = FieldInfo(alias="equityValuationAdjustments", default=None) - """Ajustes de avaliação patrimonial.""" - - financial_assets: Optional[float] = FieldInfo(alias="financialAssets", default=None) - """Ativos financeiros (agregado de instrumentos financeiros no ativo).""" - - financial_assets_at_amortized_cost: Optional[float] = FieldInfo( - alias="financialAssetsAtAmortizedCost", default=None - ) - """Ativos financeiros ao custo amortizado.""" - - financial_assets_measured_at_fair_value_through_other_comprehensive_income: Optional[float] = FieldInfo( - alias="financialAssetsMeasuredAtFairValueThroughOtherComprehensiveIncome", default=None - ) - """ - Ativos financeiros mensurados a valor justo por outros resultados abrangentes - (FVOCI). - """ - - financial_assets_measured_at_fair_value_through_profit_or_loss: Optional[float] = FieldInfo( - alias="financialAssetsMeasuredAtFairValueThroughProfitOrLoss", default=None - ) - """Ativos financeiros mensurados a valor justo por meio do resultado (FVTPL).""" - - financial_investments_measured_at_amortized_cost: Optional[float] = FieldInfo( - alias="financialInvestmentsMeasuredAtAmortizedCost", default=None - ) - """Investimentos financeiros mensurados ao custo amortizado.""" - - financial_investments_measured_at_fair_value_through_other_comprehensive_income: Optional[float] = FieldInfo( - alias="financialInvestmentsMeasuredAtFairValueThroughOtherComprehensiveIncome", default=None - ) - """ - Investimentos financeiros mensurados a valor justo por outros resultados - abrangentes. - """ - - financial_liabilities_at_amortized_cost: Optional[float] = FieldInfo( - alias="financialLiabilitiesAtAmortizedCost", default=None - ) - """Passivos financeiros ao custo amortizado.""" - - financial_liabilities_measured_at_fair_value_through_income: Optional[float] = FieldInfo( - alias="financialLiabilitiesMeasuredAtFairValueThroughIncome", default=None - ) - """Passivos financeiros mensurados a valor justo por meio do resultado.""" - - foreign_suppliers: Optional[float] = FieldInfo(alias="foreignSuppliers", default=None) - """Fornecedores estrangeiros.""" - - good_will: Optional[float] = FieldInfo(alias="goodWill", default=None) - """Ágio por expectativa de rentabilidade futura (Goodwill).""" - - insurance_and_reinsurance: Optional[float] = FieldInfo(alias="insuranceAndReinsurance", default=None) - """Provisões/obrigações de seguros e resseguros.""" - - intangible_asset: Optional[float] = FieldInfo(alias="intangibleAsset", default=None) - """Ativo intangível (valor agregado).""" - - intangible_assets: Optional[float] = FieldInfo(alias="intangibleAssets", default=None) - """Ativos intangíveis (marcas, patentes, etc.).""" + end_date: str = FieldInfo(alias="endDate") + """Data de referência""" inventory: Optional[float] = None - """Estoques.""" - - investment_properties: Optional[float] = FieldInfo(alias="investmentProperties", default=None) - """Propriedades para investimento.""" - - investments: Optional[float] = None - """Investimentos (participações e outros).""" - - lease_financing: Optional[float] = FieldInfo(alias="leaseFinancing", default=None) - """Financiamento por arrendamento mercantil (circulante).""" - - loans_and_financing: Optional[float] = FieldInfo(alias="loansAndFinancing", default=None) - """Empréstimos e financiamentos (circulante).""" - - loans_and_financing_in_foreign_currency: Optional[float] = FieldInfo( - alias="loansAndFinancingInForeignCurrency", default=None - ) - """Empréstimos e financiamentos em moeda estrangeira (circulante).""" - - loans_and_financing_in_national_currency: Optional[float] = FieldInfo( - alias="loansAndFinancingInNationalCurrency", default=None - ) - """Empréstimos e financiamentos em moeda nacional (circulante).""" - - long_term_accounts_payable: Optional[float] = FieldInfo(alias="longTermAccountsPayable", default=None) - """Fornecedores/contas a pagar de longo prazo.""" - - long_term_accounts_receivable_from_clients: Optional[float] = FieldInfo( - alias="longTermAccountsReceivableFromClients", default=None - ) - """Contas a receber de clientes - longo prazo.""" - - long_term_assets: Optional[float] = FieldInfo(alias="longTermAssets", default=None) - """Total do ativo não circulante (agregado).""" - - long_term_biological_assets: Optional[float] = FieldInfo(alias="longTermBiologicalAssets", default=None) - """Ativos biológicos de longo prazo.""" - - long_term_capitalization: Optional[float] = FieldInfo(alias="longTermCapitalization", default=None) - """Obrigações de capitalização de longo prazo.""" - - long_term_complementary_pension: Optional[float] = FieldInfo(alias="longTermComplementaryPension", default=None) - """Obrigações de previdência complementar de longo prazo.""" - - long_term_debentures: Optional[float] = FieldInfo(alias="longTermDebentures", default=None) - """Debêntures (passivo não circulante).""" - - long_term_debits_from_operations: Optional[float] = FieldInfo(alias="longTermDebitsFromOperations", default=None) - """Débitos de operações (longo prazo).""" + """Estoques""" long_term_debt: Optional[float] = FieldInfo(alias="longTermDebt", default=None) - """Dívida de longo prazo (empréstimos e financiamentos não circulantes).""" - - long_term_deferred_taxes: Optional[float] = FieldInfo(alias="longTermDeferredTaxes", default=None) - """Tributos diferidos (Ativo Não Circulante).""" - - long_term_financial_investments_measured_at_fair_value_through_income: Optional[float] = FieldInfo( - alias="longTermFinancialInvestmentsMeasuredAtFairValueThroughIncome", default=None - ) - """ - Investimentos financeiros de longo prazo mensurados a valor justo por meio do - resultado. - """ - - long_term_insurance_and_reinsurance: Optional[float] = FieldInfo( - alias="longTermInsuranceAndReinsurance", default=None - ) - """Obrigações de seguros e resseguros de longo prazo.""" - - long_term_inventory: Optional[float] = FieldInfo(alias="longTermInventory", default=None) - """Estoques de longo prazo.""" + """Dívida de longo prazo""" long_term_investments: Optional[float] = FieldInfo(alias="longTermInvestments", default=None) - """Investimentos de longo prazo.""" - - long_term_lease_financing: Optional[float] = FieldInfo(alias="longTermLeaseFinancing", default=None) - """Financiamento por arrendamento mercantil (não circulante).""" - - long_term_liabilities: Optional[float] = FieldInfo(alias="longTermLiabilities", default=None) - """Total do passivo de longo prazo.""" - - long_term_loans_and_financing: Optional[float] = FieldInfo(alias="longTermLoansAndFinancing", default=None) - """Empréstimos e financiamentos (não circulante).""" - - long_term_loans_and_financing_in_foreign_currency: Optional[float] = FieldInfo( - alias="longTermLoansAndFinancingInForeignCurrency", default=None - ) - """Empréstimos e financiamentos em moeda estrangeira (não circulante).""" - - long_term_loans_and_financing_in_national_currency: Optional[float] = FieldInfo( - alias="longTermLoansAndFinancingInNationalCurrency", default=None - ) - """Empréstimos e financiamentos em moeda nacional (não circulante).""" - - long_term_prepaid_expenses: Optional[float] = FieldInfo(alias="longTermPrepaidExpenses", default=None) - """Despesas antecipadas de longo prazo.""" - - long_term_provisions: Optional[float] = FieldInfo(alias="longTermProvisions", default=None) - """Provisões (passivo não circulante).""" - - long_term_realizable_assets: Optional[float] = FieldInfo(alias="longTermRealizableAssets", default=None) - """Ativo realizável a longo prazo.""" - - long_term_receivables: Optional[float] = FieldInfo(alias="longTermReceivables", default=None) - """Contas a receber de longo prazo.""" - - long_term_technical_provisions: Optional[float] = FieldInfo(alias="longTermTechnicalProvisions", default=None) - """Provisões técnicas de longo prazo.""" - - minority_interest: Optional[float] = FieldInfo(alias="minorityInterest", default=None) - """Participação de não controladores (no patrimônio líquido).""" - - national_suppliers: Optional[float] = FieldInfo(alias="nationalSuppliers", default=None) - """Fornecedores nacionais.""" + """Investimentos de longo prazo""" net_receivables: Optional[float] = FieldInfo(alias="netReceivables", default=None) - """Contas a receber líquidas (clientes).""" - - net_tangible_assets: Optional[float] = FieldInfo(alias="netTangibleAssets", default=None) - """Ativos tangíveis líquidos (Ativo Total - Intangíveis - Passivo Total).""" - - non_controlling_shareholders_equity: Optional[float] = FieldInfo( - alias="nonControllingShareholdersEquity", default=None - ) - """Participação dos não controladores no patrimônio líquido.""" - - non_current_assets: Optional[float] = FieldInfo(alias="nonCurrentAssets", default=None) - """Total do ativo não circulante (sinônimo de `longTermAssets`).""" - - non_current_liabilities: Optional[float] = FieldInfo(alias="nonCurrentLiabilities", default=None) - """Total do passivo não circulante.""" - - other_accounts_receivable: Optional[float] = FieldInfo(alias="otherAccountsReceivable", default=None) - """Outras contas a receber.""" + """Contas a receber""" other_assets: Optional[float] = FieldInfo(alias="otherAssets", default=None) - """Outros ativos não circulantes.""" - - other_comprehensive_results: Optional[float] = FieldInfo(alias="otherComprehensiveResults", default=None) - """Outros resultados abrangentes.""" + """Outros ativos""" other_current_assets: Optional[float] = FieldInfo(alias="otherCurrentAssets", default=None) - """Outros ativos circulantes.""" - - other_current_liab: Optional[float] = FieldInfo(alias="otherCurrentLiab", default=None) - """Outros passivos circulantes.""" - - other_current_liabilities: Optional[float] = FieldInfo(alias="otherCurrentLiabilities", default=None) - """Outros passivos circulantes (sinônimo de `otherCurrentLiab`).""" - - other_debits: Optional[float] = FieldInfo(alias="otherDebits", default=None) - """Outros débitos.""" - - other_liab: Optional[float] = FieldInfo(alias="otherLiab", default=None) - """Outros passivos não circulantes.""" - - other_liabilities: Optional[float] = FieldInfo(alias="otherLiabilities", default=None) - """Outros passivos.""" - - other_long_term_obligations: Optional[float] = FieldInfo(alias="otherLongTermObligations", default=None) - """Outras obrigações (passivo não circulante).""" - - other_long_term_provisions: Optional[float] = FieldInfo(alias="otherLongTermProvisions", default=None) - """Outras provisões de longo prazo.""" - - other_long_term_receivables: Optional[float] = FieldInfo(alias="otherLongTermReceivables", default=None) - """Outros créditos/recebíveis de longo prazo.""" - - other_non_current_assets: Optional[float] = FieldInfo(alias="otherNonCurrentAssets", default=None) - """Outros ativos não circulantes (detalhamento).""" - - other_non_current_liabilities: Optional[float] = FieldInfo(alias="otherNonCurrentLiabilities", default=None) - """Outros passivos não circulantes.""" - - other_obligations: Optional[float] = FieldInfo(alias="otherObligations", default=None) - """Outras obrigações (circulante).""" - - other_operations: Optional[float] = FieldInfo(alias="otherOperations", default=None) - """Outras contas operacionais no ativo.""" - - other_provisions: Optional[float] = FieldInfo(alias="otherProvisions", default=None) - """Outras provisões (diversas).""" - - other_stockholder_equity: Optional[float] = FieldInfo(alias="otherStockholderEquity", default=None) - """Outros componentes do patrimônio líquido.""" - - other_values_and_assets: Optional[float] = FieldInfo(alias="otherValuesAndAssets", default=None) - """Outros valores e bens.""" - - prepaid_expenses: Optional[float] = FieldInfo(alias="prepaidExpenses", default=None) - """Despesas antecipadas.""" - - profit_reserves: Optional[float] = FieldInfo(alias="profitReserves", default=None) - """Reservas de lucros.""" - - profits_and_revenues_to_be_appropriated: Optional[float] = FieldInfo( - alias="profitsAndRevenuesToBeAppropriated", default=None - ) - """Lucros e receitas a apropriar.""" + """Outros ativos circulantes""" property_plant_equipment: Optional[float] = FieldInfo(alias="propertyPlantEquipment", default=None) - """Imobilizado (propriedades, instalações e equipamentos).""" - - providers: Optional[float] = None - """Fornecedores (sinônimo de `accountsPayable`).""" - - provisions: Optional[float] = None - """Provisões (passivo).""" - - realized_share_capital: Optional[float] = FieldInfo(alias="realizedShareCapital", default=None) - """Capital social realizado (sinônimo de `commonStock`).""" - - retained_earnings: Optional[float] = FieldInfo(alias="retainedEarnings", default=None) - """Lucros/Prejuízos acumulados.""" - - revaluation_reserves: Optional[float] = FieldInfo(alias="revaluationReserves", default=None) - """Reservas de reavaliação.""" - - securities_and_credits_receivable: Optional[float] = FieldInfo(alias="securitiesAndCreditsReceivable", default=None) - """Títulos e créditos a receber.""" - - shareholders_equity: Optional[float] = FieldInfo(alias="shareholdersEquity", default=None) - """Patrimônio líquido (sinônimo de `totalStockholderEquity`).""" - - shareholdings: Optional[float] = None - """Participações societárias.""" + """Imobilizado""" short_long_term_debt: Optional[float] = FieldInfo(alias="shortLongTermDebt", default=None) - """Dívida de curto prazo (empréstimos e financiamentos circulantes).""" + """Dívida de curto/longo prazo""" short_term_investments: Optional[float] = FieldInfo(alias="shortTermInvestments", default=None) - """Aplicações financeiras de curto prazo.""" - - social_and_labor_obligations: Optional[float] = FieldInfo(alias="socialAndLaborObligations", default=None) - """Obrigações sociais e trabalhistas.""" + """Investimentos de curto prazo""" - symbol: Optional[str] = None - """Ticker do ativo ao qual o balanço se refere.""" - - taxes_to_recover: Optional[float] = FieldInfo(alias="taxesToRecover", default=None) - """Impostos a recuperar.""" - - tax_liabilities: Optional[float] = FieldInfo(alias="taxLiabilities", default=None) - """Obrigações fiscais (passivo).""" - - tax_obligations: Optional[float] = FieldInfo(alias="taxObligations", default=None) - """Obrigações fiscais (passivo circulante).""" - - technical_provisions: Optional[float] = FieldInfo(alias="technicalProvisions", default=None) - """Provisões técnicas (seguradoras/previdência).""" - - third_party_deposits: Optional[float] = FieldInfo(alias="thirdPartyDeposits", default=None) - """Depósitos de terceiros.""" + symbol: str + """Ticker do ativo""" total_assets: Optional[float] = FieldInfo(alias="totalAssets", default=None) - """Total do ativo.""" + """Total de ativos""" total_current_assets: Optional[float] = FieldInfo(alias="totalCurrentAssets", default=None) - """Total do ativo circulante.""" + """Total ativo circulante""" total_current_liabilities: Optional[float] = FieldInfo(alias="totalCurrentLiabilities", default=None) - """Total do passivo circulante.""" + """Passivo circulante total""" total_liab: Optional[float] = FieldInfo(alias="totalLiab", default=None) - """Total do passivo (circulante + não circulante).""" - - total_liabilities: Optional[float] = FieldInfo(alias="totalLiabilities", default=None) - """Total do passivo.""" + """Passivo total""" total_stockholder_equity: Optional[float] = FieldInfo(alias="totalStockholderEquity", default=None) - """Total do patrimônio líquido.""" - - treasury_stock: Optional[float] = FieldInfo(alias="treasuryStock", default=None) - """Ações em tesouraria.""" + """Patrimônio líquido""" - type: Optional[Literal["yearly", "quarterly"]] = None - """ - Indica a periodicidade do balanço: `yearly` (anual) ou `quarterly` (trimestral). - """ + type: str + """Tipo (yearly, quarterly)""" - updated_at: Optional[date] = FieldInfo(alias="updatedAt", default=None) - """Data da última atualização deste registro (YYYY-MM-DD).""" + updated_at: Optional[str] = FieldInfo(alias="updatedAt", default=None) + """Data de atualização""" diff --git a/src/brapi/types/cashflow_entry.py b/src/brapi/types/cashflow_entry.py deleted file mode 100644 index a17f213..0000000 --- a/src/brapi/types/cashflow_entry.py +++ /dev/null @@ -1,93 +0,0 @@ -# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -from typing import Optional -from datetime import date -from typing_extensions import Literal - -from pydantic import Field as FieldInfo - -from .._models import BaseModel - -__all__ = ["CashflowEntry"] - - -class CashflowEntry(BaseModel): - """ - Representa os dados de uma Demonstração do Fluxo de Caixa (DFC) para um período específico (anual ou trimestral). - """ - - adjustments_to_profit_or_loss: Optional[float] = FieldInfo(alias="adjustmentsToProfitOrLoss", default=None) - """ - Ajustes ao lucro/prejuízo (depreciação, amortização, equivalência patrimonial, - variações não caixa). - """ - - cash_generated_in_operations: Optional[float] = FieldInfo(alias="cashGeneratedInOperations", default=None) - """Caixa gerado nas operações (após variações no capital de giro).""" - - changes_in_assets_and_liabilities: Optional[float] = FieldInfo(alias="changesInAssetsAndLiabilities", default=None) - """ - Variações em Ativos e Passivos Operacionais (Clientes, Estoques, Fornecedores, - etc.). - """ - - end_date: Optional[date] = FieldInfo(alias="endDate", default=None) - """Data de término do período fiscal ao qual a DFC se refere (YYYY-MM-DD).""" - - exchange_variation_without_cash: Optional[float] = FieldInfo(alias="exchangeVariationWithoutCash", default=None) - """Variação cambial sem efeito caixa (ajuste de conversão).""" - - final_cash_balance: Optional[float] = FieldInfo(alias="finalCashBalance", default=None) - """Saldo Final de Caixa e Equivalentes no final do período.""" - - financing_cash_flow: Optional[float] = FieldInfo(alias="financingCashFlow", default=None) - """ - Fluxo de Caixa das Atividades de Financiamento (FCF) (Captação/Pagamento de - Empréstimos, Emissão/Recompra de Ações, Dividendos pagos). - """ - - foreign_exchange_rate_without_cash: Optional[float] = FieldInfo( - alias="foreignExchangeRateWithoutCash", default=None - ) - """Efeito da Variação Cambial sobre o Caixa e Equivalentes.""" - - income_from_operations: Optional[float] = FieldInfo(alias="incomeFromOperations", default=None) - """Caixa Gerado nas Operações (antes das variações de ativos/passivos).""" - - increase_or_decrease_in_cash: Optional[float] = FieldInfo(alias="increaseOrDecreaseInCash", default=None) - """ - Aumento ou Redução Líquida de Caixa e Equivalentes (FCO + FCI + FCF + Variação - Cambial). - """ - - initial_cash_balance: Optional[float] = FieldInfo(alias="initialCashBalance", default=None) - """Saldo Inicial de Caixa e Equivalentes no início do período.""" - - investment_cash_flow: Optional[float] = FieldInfo(alias="investmentCashFlow", default=None) - """ - Fluxo de Caixa das Atividades de Investimento (FCI) (Compra/Venda de - Imobilizado, Investimentos). - """ - - net_income_before_taxes: Optional[float] = FieldInfo(alias="netIncomeBeforeTaxes", default=None) - """ - Lucro líquido antes dos impostos (base para reconciliação pelo método indireto). - """ - - operating_cash_flow: Optional[float] = FieldInfo(alias="operatingCashFlow", default=None) - """Fluxo de Caixa das Atividades Operacionais (FCO).""" - - other_operating_activities: Optional[float] = FieldInfo(alias="otherOperatingActivities", default=None) - """Outras Atividades Operacionais (Juros pagos/recebidos, Impostos pagos, etc.).""" - - symbol: Optional[str] = None - """Ticker do ativo ao qual a DFC se refere.""" - - type: Optional[Literal["yearly", "quarterly"]] = None - """Indica a periodicidade da DFC: `yearly` (anual) ou `quarterly` (trimestral).""" - - updated_at: Optional[date] = FieldInfo(alias="updatedAt", default=None) - """ - Data da última atualização deste registro específico na fonte de dados - (YYYY-MM-DD). - """ diff --git a/src/brapi/types/default_key_statistics_entry.py b/src/brapi/types/default_key_statistics_entry.py deleted file mode 100644 index 44b1660..0000000 --- a/src/brapi/types/default_key_statistics_entry.py +++ /dev/null @@ -1,142 +0,0 @@ -# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -from typing import Optional -from datetime import date -from typing_extensions import Literal - -from pydantic import Field as FieldInfo - -from .._models import BaseModel - -__all__ = ["DefaultKeyStatisticsEntry"] - - -class DefaultKeyStatisticsEntry(BaseModel): - """ - Representa um conjunto de principais indicadores e estatísticas financeiras para um período (TTM, anual ou trimestral). - """ - - api_52_week_change: Optional[float] = FieldInfo(alias="52WeekChange", default=None) - """Variação percentual do preço da ação nas últimas 52 semanas.""" - - beta: Optional[float] = None - """Beta da ação (sensibilidade em relação ao mercado).""" - - book_value: Optional[float] = FieldInfo(alias="bookValue", default=None) - """Valor Patrimonial por Ação (VPA): Patrimônio Líquido / Ações em Circulação.""" - - dividend_yield: Optional[float] = FieldInfo(alias="dividendYield", default=None) - """Dividend Yield (provento anualizado sobre o preço atual).""" - - earnings_annual_growth: Optional[float] = FieldInfo(alias="earningsAnnualGrowth", default=None) - """ - Crescimento percentual do lucro líquido no último ano fiscal completo em relação - ao ano anterior. - """ - - earnings_quarterly_growth: Optional[float] = FieldInfo(alias="earningsQuarterlyGrowth", default=None) - """ - Crescimento percentual do lucro líquido no último trimestre em relação ao mesmo - trimestre do ano anterior (YoY). - """ - - enterprise_to_ebitda: Optional[float] = FieldInfo(alias="enterpriseToEbitda", default=None) - """Múltiplo EV/EBITDA (Enterprise Value / EBITDA TTM).""" - - enterprise_to_revenue: Optional[float] = FieldInfo(alias="enterpriseToRevenue", default=None) - """Múltiplo EV/Receita (Enterprise Value / Receita Líquida TTM).""" - - enterprise_value: Optional[float] = FieldInfo(alias="enterpriseValue", default=None) - """Valor da Firma (Enterprise Value - EV): Market Cap + Dívida Total - Caixa.""" - - float_shares: Optional[float] = FieldInfo(alias="floatShares", default=None) - """Ações em livre circulação (free float).""" - - forward_eps: Optional[float] = FieldInfo(alias="forwardEps", default=None) - """Lucro Por Ação projetado (próximo período).""" - - forward_pe: Optional[float] = FieldInfo(alias="forwardPE", default=None) - """ - Preço / Lucro Projetado (Forward P/E): Preço da Ação / LPA estimado para o - próximo período. - """ - - held_percent_insiders: Optional[float] = FieldInfo(alias="heldPercentInsiders", default=None) - """Percentual de ações detidas por insiders (administradores, controladores).""" - - held_percent_institutions: Optional[float] = FieldInfo(alias="heldPercentInstitutions", default=None) - """ - Percentual de ações detidas por instituições (fundos, investidores - institucionais). - """ - - implied_shares_outstanding: Optional[float] = FieldInfo(alias="impliedSharesOutstanding", default=None) - """Ações implícitas em circulação (considerando diluição/derivativos).""" - - last_dividend_date: Optional[date] = FieldInfo(alias="lastDividendDate", default=None) - """Data de pagamento (ou 'Data Com') do último dividendo/JCP (YYYY-MM-DD).""" - - last_dividend_value: Optional[float] = FieldInfo(alias="lastDividendValue", default=None) - """Valor do último dividendo ou JCP pago por ação.""" - - last_fiscal_year_end: Optional[date] = FieldInfo(alias="lastFiscalYearEnd", default=None) - """Data de encerramento do último ano fiscal (YYYY-MM-DD).""" - - last_split_date: Optional[float] = FieldInfo(alias="lastSplitDate", default=None) - """Data do último desdobramento/grupamento (timestamp UNIX em segundos).""" - - last_split_factor: Optional[str] = FieldInfo(alias="lastSplitFactor", default=None) - """Fator do último desdobramento/grupamento (ex.: 2:1, 1:10).""" - - most_recent_quarter: Optional[date] = FieldInfo(alias="mostRecentQuarter", default=None) - """ - Data de término do trimestre mais recente considerado nos cálculos (YYYY-MM-DD). - """ - - net_income_to_common: Optional[float] = FieldInfo(alias="netIncomeToCommon", default=None) - """Lucro Líquido atribuível aos acionistas ordinários (controladores).""" - - next_fiscal_year_end: Optional[date] = FieldInfo(alias="nextFiscalYearEnd", default=None) - """Data de encerramento do próximo ano fiscal (YYYY-MM-DD).""" - - peg_ratio: Optional[float] = FieldInfo(alias="pegRatio", default=None) - """Índice PEG (P/E dividido pelo crescimento esperado dos lucros).""" - - price_to_book: Optional[float] = FieldInfo(alias="priceToBook", default=None) - """Preço sobre Valor Patrimonial (P/VP): Preço da Ação / VPA.""" - - profit_margins: Optional[float] = FieldInfo(alias="profitMargins", default=None) - """Margem de Lucro Líquida (Lucro Líquido / Receita Líquida). - - Geralmente em base TTM ou anual. - """ - - sand_p52_week_change: Optional[float] = FieldInfo(alias="SandP52WeekChange", default=None) - """Variação percentual do índice S&P 500 nas últimas 52 semanas (para referência).""" - - shares_outstanding: Optional[float] = FieldInfo(alias="sharesOutstanding", default=None) - """Número total de ações ordinárias em circulação.""" - - symbol: Optional[str] = None - """Ticker do ativo ao qual as estatísticas se referem.""" - - total_assets: Optional[float] = FieldInfo(alias="totalAssets", default=None) - """Valor total dos ativos registrado no último balanço (anual ou trimestral).""" - - trailing_eps: Optional[float] = FieldInfo(alias="trailingEps", default=None) - """Lucro Por Ação (LPA) dos Últimos 12 Meses (TTM).""" - - type: Optional[Literal["yearly", "quarterly", "ttm"]] = None - """ - Periodicidade dos dados: `yearly` (anual), `quarterly` (trimestral), `ttm` - (Trailing Twelve Months - últimos 12 meses). - """ - - updated_at: Optional[date] = FieldInfo(alias="updatedAt", default=None) - """ - Data da última atualização deste registro específico na fonte de dados - (YYYY-MM-DD). - """ - - ytd_return: Optional[float] = FieldInfo(alias="ytdReturn", default=None) - """Retorno percentual do preço da ação desde o início do ano atual (Year-to-Date).""" diff --git a/src/brapi/types/financial_data_entry.py b/src/brapi/types/financial_data_entry.py index 3b6a05b..8f08457 100644 --- a/src/brapi/types/financial_data_entry.py +++ b/src/brapi/types/financial_data_entry.py @@ -1,8 +1,6 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. from typing import Optional -from datetime import date -from typing_extensions import Literal from pydantic import Field as FieldInfo @@ -12,126 +10,79 @@ class FinancialDataEntry(BaseModel): - """ - Representa um conjunto de dados e indicadores financeiros calculados para um período (TTM, anual ou trimestral). - """ + """Dados financeiros e indicadores TTM""" current_price: Optional[float] = FieldInfo(alias="currentPrice", default=None) - """Preço atual da ação (pode ser ligeiramente defasado).""" + """Preço atual""" current_ratio: Optional[float] = FieldInfo(alias="currentRatio", default=None) - """Índice de Liquidez Corrente (Ativo Circulante / Passivo Circulante).""" + """Liquidez corrente""" debt_to_equity: Optional[float] = FieldInfo(alias="debtToEquity", default=None) - """Índice Dívida Líquida / Patrimônio Líquido.""" + """Dívida/PL""" earnings_growth: Optional[float] = FieldInfo(alias="earningsGrowth", default=None) - """ - Crescimento do Lucro Líquido (geralmente trimestral YoY, como - `earningsQuarterlyGrowth`). - """ + """Crescimento do lucro""" ebitda: Optional[float] = None - """Lucro Antes de Juros, Impostos, Depreciação e Amortização (LAJIDA ou EBITDA). - - Geralmente TTM. - """ + """EBITDA""" ebitda_margins: Optional[float] = FieldInfo(alias="ebitdaMargins", default=None) - """Margem EBITDA (EBITDA TTM / Receita Líquida TTM).""" + """Margem EBITDA""" financial_currency: Optional[str] = FieldInfo(alias="financialCurrency", default=None) - """Moeda na qual os dados financeiros são reportados (ex: `BRL`, `USD`).""" + """Moeda""" free_cashflow: Optional[float] = FieldInfo(alias="freeCashflow", default=None) - """Fluxo de Caixa Livre (FCO - CAPEX) - (geralmente TTM).""" + """Fluxo de caixa livre""" gross_margins: Optional[float] = FieldInfo(alias="grossMargins", default=None) - """Margem Bruta (Lucro Bruto TTM / Receita Líquida TTM).""" + """Margem bruta""" gross_profits: Optional[float] = FieldInfo(alias="grossProfits", default=None) - """Lucro Bruto (geralmente TTM).""" - - number_of_analyst_opinions: Optional[float] = FieldInfo(alias="numberOfAnalystOpinions", default=None) - """Número de opiniões de analistas consideradas.""" + """Lucro bruto""" operating_cashflow: Optional[float] = FieldInfo(alias="operatingCashflow", default=None) - """Fluxo de Caixa das Operações (FCO) - (geralmente TTM).""" + """Fluxo de caixa operacional""" operating_margins: Optional[float] = FieldInfo(alias="operatingMargins", default=None) - """Margem Operacional (EBIT TTM / Receita Líquida TTM).""" + """Margem operacional""" profit_margins: Optional[float] = FieldInfo(alias="profitMargins", default=None) - """Margem Líquida (Lucro Líquido TTM / Receita Líquida TTM). - - Sinônimo do campo de mesmo nome em `DefaultKeyStatisticsEntry`. - """ + """Margem de lucro""" quick_ratio: Optional[float] = FieldInfo(alias="quickRatio", default=None) - """Índice de Liquidez Seca ((Ativo Circulante - Estoques) / Passivo Circulante).""" - - recommendation_key: Optional[str] = FieldInfo(alias="recommendationKey", default=None) - """Resumo da recomendação (ex.: strong_buy, buy, hold, sell, strong_sell).""" - - recommendation_mean: Optional[float] = FieldInfo(alias="recommendationMean", default=None) - """Média de recomendações dos analistas (1=Compra Forte, 5=Venda Forte).""" + """Liquidez seca""" return_on_assets: Optional[float] = FieldInfo(alias="returnOnAssets", default=None) - """Retorno sobre Ativos (ROA): Lucro Líquido TTM / Ativo Total Médio.""" + """ROA""" return_on_equity: Optional[float] = FieldInfo(alias="returnOnEquity", default=None) - """ - Retorno sobre Patrimônio Líquido (ROE): Lucro Líquido TTM / Patrimônio Líquido - Médio. - """ + """ROE""" revenue_growth: Optional[float] = FieldInfo(alias="revenueGrowth", default=None) - """Crescimento da Receita Líquida (geralmente trimestral YoY).""" + """Crescimento da receita""" revenue_per_share: Optional[float] = FieldInfo(alias="revenuePerShare", default=None) - """Receita Líquida por Ação (Receita Líquida TTM / Ações em Circulação).""" - - symbol: Optional[str] = None - """Ticker do ativo ao qual os dados se referem.""" + """Receita por ação""" - target_high_price: Optional[float] = FieldInfo(alias="targetHighPrice", default=None) - """Preço-alvo mais alto estimado por analistas.""" - - target_low_price: Optional[float] = FieldInfo(alias="targetLowPrice", default=None) - """Preço-alvo mais baixo estimado por analistas.""" - - target_mean_price: Optional[float] = FieldInfo(alias="targetMeanPrice", default=None) - """Preço-alvo médio estimado por analistas.""" - - target_median_price: Optional[float] = FieldInfo(alias="targetMedianPrice", default=None) - """Preço-alvo mediano estimado por analistas.""" + symbol: str + """Ticker do ativo""" total_cash: Optional[float] = FieldInfo(alias="totalCash", default=None) - """ - Caixa e Equivalentes de Caixa + Aplicações Financeiras de Curto Prazo (último - balanço). - """ + """Caixa total""" total_cash_per_share: Optional[float] = FieldInfo(alias="totalCashPerShare", default=None) - """Caixa Total por Ação (Caixa Total / Ações em Circulação).""" + """Caixa por ação""" total_debt: Optional[float] = FieldInfo(alias="totalDebt", default=None) - """ - Dívida Bruta Total (Dívida de Curto Prazo + Dívida de Longo Prazo - último - balanço). - """ + """Dívida total""" total_revenue: Optional[float] = FieldInfo(alias="totalRevenue", default=None) - """Receita Líquida Total (geralmente TTM).""" - - type: Optional[Literal["yearly", "quarterly", "ttm"]] = None - """ - Periodicidade dos dados: `yearly` (anual), `quarterly` (trimestral), `ttm` - (Trailing Twelve Months). - """ - - updated_at: Optional[date] = FieldInfo(alias="updatedAt", default=None) - """ - Data da última atualização deste registro específico na fonte de dados - (YYYY-MM-DD). - """ + """Receita total""" + + type: Optional[str] = None + """Tipo (ttm, yearly, quarterly)""" + + updated_at: Optional[str] = FieldInfo(alias="updatedAt", default=None) + """Data de atualização""" diff --git a/src/brapi/types/income_statement_entry.py b/src/brapi/types/income_statement_entry.py deleted file mode 100644 index 34bfc0b..0000000 --- a/src/brapi/types/income_statement_entry.py +++ /dev/null @@ -1,202 +0,0 @@ -# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -from typing import Optional -from datetime import date -from typing_extensions import Literal - -from pydantic import Field as FieldInfo - -from .._models import BaseModel - -__all__ = ["IncomeStatementEntry"] - - -class IncomeStatementEntry(BaseModel): - """ - Representa os dados de uma Demonstração do Resultado do Exercício (DRE) para um período específico (anual ou trimestral). - """ - - id: Optional[str] = None - """Identificador único deste registro de DRE (interno).""" - - administrative_costs: Optional[float] = FieldInfo(alias="administrativeCosts", default=None) - """Despesas Administrativas (detalhamento, pode estar contido em SG&A).""" - - basic_earnings_per_common_share: Optional[float] = FieldInfo(alias="basicEarningsPerCommonShare", default=None) - """Lucro Básico por Ação Ordinária (ON).""" - - basic_earnings_per_preferred_share: Optional[float] = FieldInfo( - alias="basicEarningsPerPreferredShare", default=None - ) - """Lucro Básico por Ação Preferencial (PN).""" - - basic_earnings_per_share: Optional[float] = FieldInfo(alias="basicEarningsPerShare", default=None) - """Lucro Básico por Ação (LPA Básico) - Geral.""" - - capitalization_operations: Optional[float] = FieldInfo(alias="capitalizationOperations", default=None) - """Resultado de Operações de Capitalização (específico para Seguradoras).""" - - claims_and_operations_costs: Optional[float] = FieldInfo(alias="claimsAndOperationsCosts", default=None) - """Custos com Sinistros e Operações (específico para Seguradoras).""" - - complementary_pension_operations: Optional[float] = FieldInfo(alias="complementaryPensionOperations", default=None) - """ - Resultado de Operações de Previdência Complementar (específico para - Seguradoras/Previdência). - """ - - cost_of_revenue: Optional[float] = FieldInfo(alias="costOfRevenue", default=None) - """Custo dos Produtos Vendidos (CPV) ou Custo dos Serviços Prestados (CSP).""" - - current_taxes: Optional[float] = FieldInfo(alias="currentTaxes", default=None) - """Imposto de Renda e Contribuição Social Correntes.""" - - deferred_taxes: Optional[float] = FieldInfo(alias="deferredTaxes", default=None) - """Imposto de Renda e Contribuição Social Diferidos.""" - - diluted_earnings_per_common_share: Optional[float] = FieldInfo(alias="dilutedEarningsPerCommonShare", default=None) - """Lucro Diluído por Ação Ordinária (ON).""" - - diluted_earnings_per_preferred_share: Optional[float] = FieldInfo( - alias="dilutedEarningsPerPreferredShare", default=None - ) - """Lucro Diluído por Ação Preferencial (PN).""" - - diluted_earnings_per_share: Optional[float] = FieldInfo(alias="dilutedEarningsPerShare", default=None) - """Lucro Diluído por Ação (LPA Diluído) - Geral.""" - - discontinued_operations: Optional[float] = FieldInfo(alias="discontinuedOperations", default=None) - """Resultado Líquido das Operações Descontinuadas.""" - - earnings_per_share: Optional[float] = FieldInfo(alias="earningsPerShare", default=None) - """Lucro por Ação (LPA) - Geral (pode ser básico ou diluído, verificar contexto).""" - - ebit: Optional[float] = None - """Lucro Antes dos Juros e Impostos (LAJIR ou EBIT). - - Geralmente igual a `operatingIncome`. - """ - - effect_of_accounting_charges: Optional[float] = FieldInfo(alias="effectOfAccountingCharges", default=None) - """Efeito de Mudanças Contábeis.""" - - end_date: Optional[date] = FieldInfo(alias="endDate", default=None) - """Data de término do período fiscal ao qual a DRE se refere (YYYY-MM-DD).""" - - equity_income_result: Optional[float] = FieldInfo(alias="equityIncomeResult", default=None) - """Resultado de Equivalência Patrimonial.""" - - extraordinary_items: Optional[float] = FieldInfo(alias="extraordinaryItems", default=None) - """Itens Extraordinários.""" - - financial_expenses: Optional[float] = FieldInfo(alias="financialExpenses", default=None) - """Despesas Financeiras (valor positivo aqui, diferente de `interestExpense`).""" - - financial_income: Optional[float] = FieldInfo(alias="financialIncome", default=None) - """Receitas Financeiras.""" - - financial_result: Optional[float] = FieldInfo(alias="financialResult", default=None) - """Resultado Financeiro Líquido.""" - - gross_profit: Optional[float] = FieldInfo(alias="grossProfit", default=None) - """Lucro Bruto (Receita Líquida - CPV/CSP).""" - - income_before_statutory_participations_and_contributions: Optional[float] = FieldInfo( - alias="incomeBeforeStatutoryParticipationsAndContributions", default=None - ) - """Resultado Antes das Participações Estatutárias.""" - - income_before_tax: Optional[float] = FieldInfo(alias="incomeBeforeTax", default=None) - """Lucro Antes do Imposto de Renda e Contribuição Social (LAIR). - - EBIT + Resultado Financeiro. - """ - - income_tax_expense: Optional[float] = FieldInfo(alias="incomeTaxExpense", default=None) - """Imposto de Renda e Contribuição Social sobre o Lucro.""" - - insurance_operations: Optional[float] = FieldInfo(alias="insuranceOperations", default=None) - """Resultado de Operações de Seguros (específico para Seguradoras).""" - - interest_expense: Optional[float] = FieldInfo(alias="interestExpense", default=None) - """Despesas Financeiras (Juros pagos). Note que este campo é negativo.""" - - losses_due_to_non_recoverability_of_assets: Optional[float] = FieldInfo( - alias="lossesDueToNonRecoverabilityOfAssets", default=None - ) - """Perdas por Não Recuperabilidade de Ativos (Impairment).""" - - minority_interest: Optional[float] = FieldInfo(alias="minorityInterest", default=None) - """Participação de Acionistas Não Controladores (no Lucro Líquido).""" - - net_income: Optional[float] = FieldInfo(alias="netIncome", default=None) - """Lucro Líquido Consolidado do Período.""" - - net_income_applicable_to_common_shares: Optional[float] = FieldInfo( - alias="netIncomeApplicableToCommonShares", default=None - ) - """Lucro Líquido Atribuível aos Acionistas Controladores (Ações Ordinárias).""" - - net_income_from_continuing_ops: Optional[float] = FieldInfo(alias="netIncomeFromContinuingOps", default=None) - """Lucro Líquido das Operações Continuadas.""" - - non_recurring: Optional[float] = FieldInfo(alias="nonRecurring", default=None) - """Itens Não Recorrentes (pode incluir outras despesas/receitas operacionais).""" - - operating_income: Optional[float] = FieldInfo(alias="operatingIncome", default=None) - """Lucro Operacional (EBIT - Earnings Before Interest and Taxes). - - Lucro Bruto - Despesas Operacionais. - """ - - other_items: Optional[float] = FieldInfo(alias="otherItems", default=None) - """Outros Itens.""" - - other_operating_expenses: Optional[float] = FieldInfo(alias="otherOperatingExpenses", default=None) - """Outras Despesas Operacionais.""" - - other_operating_income: Optional[float] = FieldInfo(alias="otherOperatingIncome", default=None) - """Outras Receitas Operacionais (detalhamento).""" - - other_operating_income_and_expenses: Optional[float] = FieldInfo( - alias="otherOperatingIncomeAndExpenses", default=None - ) - """Outras Receitas e Despesas Operacionais (agregado).""" - - profit_sharing_and_statutory_contributions: Optional[float] = FieldInfo( - alias="profitSharingAndStatutoryContributions", default=None - ) - """Participações nos Lucros e Contribuições Estatutárias.""" - - reinsurance_operations: Optional[float] = FieldInfo(alias="reinsuranceOperations", default=None) - """Resultado de Operações de Resseguros (específico para Seguradoras).""" - - research_development: Optional[float] = FieldInfo(alias="researchDevelopment", default=None) - """Despesas com Pesquisa e Desenvolvimento.""" - - sales_expenses: Optional[float] = FieldInfo(alias="salesExpenses", default=None) - """Despesas com Vendas (detalhamento, pode estar contido em SG&A).""" - - selling_general_administrative: Optional[float] = FieldInfo(alias="sellingGeneralAdministrative", default=None) - """Despesas com Vendas, Gerais e Administrativas.""" - - symbol: Optional[str] = None - """Ticker do ativo ao qual a DRE se refere.""" - - total_operating_expenses: Optional[float] = FieldInfo(alias="totalOperatingExpenses", default=None) - """Total das Despesas Operacionais (P&D + SG&A + Outras).""" - - total_other_income_expense_net: Optional[float] = FieldInfo(alias="totalOtherIncomeExpenseNet", default=None) - """Resultado Financeiro Líquido + Outras Receitas/Despesas.""" - - total_revenue: Optional[float] = FieldInfo(alias="totalRevenue", default=None) - """Receita Operacional Líquida.""" - - type: Optional[Literal["yearly", "quarterly"]] = None - """Indica a periodicidade da DRE: `yearly` (anual) ou `quarterly` (trimestral).""" - - updated_at: Optional[date] = FieldInfo(alias="updatedAt", default=None) - """ - Data da última atualização deste registro específico na fonte de dados - (YYYY-MM-DD). - """ diff --git a/src/brapi/types/quote_list_params.py b/src/brapi/types/quote_list_params.py index 9038560..0775148 100644 --- a/src/brapi/types/quote_list_params.py +++ b/src/brapi/types/quote_list_params.py @@ -11,76 +11,27 @@ class QuoteListParams(TypedDict, total=False): token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + """Token de autenticação (alternativa ao header Authorization)""" - **Formas de Envio:** + limit: str + """Número máximo de resultados""" - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ - - limit: int - """**Opcional.** Número máximo de ativos a serem retornados por página. - - O valor padrão pode variar. - """ - - page: int - """ - **Opcional.** Número da página dos resultados a ser retornada, considerando o - `limit` especificado. Começa em 1. - """ + page: str + """Número da página (paginação)""" search: str - """**Opcional.** Termo para buscar ativos por ticker (correspondência parcial). + """Termo de busca para filtrar ativos""" - Ex: `PETR` encontrará `PETR4`, `PETR3`. - """ - - sector: Literal[ - "Retail Trade", - "Energy Minerals", - "Health Services", - "Utilities", - "Finance", - "Consumer Services", - "Consumer Non-Durables", - "Non-Energy Minerals", - "Commercial Services", - "Distribution Services", - "Transportation", - "Technology Services", - "Process Industries", - "Communications", - "Producer Manufacturing", - "Miscellaneous", - "Electronic Technology", - "Industrial Services", - "Health Technology", - "Consumer Durables", - ] - """**Opcional.** Filtra os resultados por setor de atuação da empresa. - - Utilize um dos valores retornados em `availableSectors`. - """ + sector: str + """Filtrar por setor""" sort_by: Annotated[ - Literal["name", "close", "change", "change_abs", "volume", "market_cap_basic", "sector"], - PropertyInfo(alias="sortBy"), + Literal["name", "close", "change", "change_abs", "volume", "market_cap_basic"], PropertyInfo(alias="sortBy") ] - """**Opcional.** Campo pelo qual os resultados serão ordenados.""" + """Campo para ordenação""" sort_order: Annotated[Literal["asc", "desc"], PropertyInfo(alias="sortOrder")] - """**Opcional.** Direção da ordenação: `asc` (ascendente) ou `desc` (descendente). - - Requer que `sortBy` seja especificado. - """ + """Ordem de classificação""" type: Literal["stock", "fund", "bdr"] - """**Opcional.** Filtra os resultados por tipo de ativo.""" + """Filtrar por tipo de ativo""" diff --git a/src/brapi/types/quote_list_response.py b/src/brapi/types/quote_list_response.py index 194ef67..37fef71 100644 --- a/src/brapi/types/quote_list_response.py +++ b/src/brapi/types/quote_list_response.py @@ -1,7 +1,6 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. from typing import List, Optional -from typing_extensions import Literal from pydantic import Field as FieldInfo @@ -11,97 +10,55 @@ class Index(BaseModel): - """Resumo de informações de um índice, geralmente retornado em listas.""" + name: str - name: Optional[str] = None - """Nome do índice (ex: `IBOVESPA`).""" - - stock: Optional[str] = None - """Ticker do índice (ex: `^BVSP`).""" + stock: str class Stock(BaseModel): - """ - Resumo de informações de um ativo (ação, FII, BDR), geralmente retornado em listas. - """ - change: Optional[float] = None - """Variação percentual do preço em relação ao fechamento anterior.""" + """Variação percentual""" close: Optional[float] = None - """Preço de fechamento mais recente ou último preço negociado.""" + """Preço de fechamento""" logo: Optional[str] = None - """URL para a imagem do logo da empresa/ativo.""" + """URL do logo""" market_cap: Optional[float] = None - """Capitalização de mercado (Preço x Quantidade de Ações). + """Capitalização de mercado""" - Pode ser nulo para FIIs ou outros tipos. - """ - - name: Optional[str] = None - """Nome do ativo ou empresa (ex: `PETROBRAS PN`).""" + name: str + """Nome da empresa""" sector: Optional[str] = None - """Setor de atuação da empresa (ex: `Energy Minerals`, `Finance`). - - Pode ser nulo ou variar para FIIs. - """ + """Setor""" - stock: Optional[str] = None - """Ticker do ativo (ex: `PETR4`, `MXRF11`).""" + stock: str + """Ticker do ativo""" - type: Optional[Literal["stock", "fund", "bdr"]] = None - """ - Tipo do ativo: `stock` (Ação), `fund` (Fundo Imobiliário/FII), `bdr` (Brazilian - Depositary Receipt). - """ + type: Optional[str] = None + """Tipo do ativo""" - volume: Optional[int] = None - """Volume financeiro negociado no último pregão ou dia atual.""" + volume: Optional[float] = None + """Volume negociado""" class QuoteListResponse(BaseModel): - """Resposta do endpoint de listagem de cotações (`/api/quote/list`).""" + available_sectors: List[str] = FieldInfo(alias="availableSectors") - available_sectors: Optional[List[str]] = FieldInfo(alias="availableSectors", default=None) - """ - Lista de todos os setores disponíveis que podem ser usados no parâmetro de - filtro `sector`. - """ + available_stock_types: List[str] = FieldInfo(alias="availableStockTypes") - available_stock_types: Optional[List[Literal["stock", "fund", "bdr"]]] = FieldInfo( - alias="availableStockTypes", default=None - ) - """ - Lista dos tipos de ativos (`stock`, `fund`, `bdr`) disponíveis que podem ser - usados no parâmetro de filtro `type`. - """ + indexes: List[Index] - current_page: Optional[int] = FieldInfo(alias="currentPage", default=None) - """Número da página atual retornada nos resultados.""" + stocks: List[Stock] - has_next_page: Optional[bool] = FieldInfo(alias="hasNextPage", default=None) - """ - Indica se existe uma próxima página de resultados (`true`) ou se esta é a última - página (`false`). - """ - - indexes: Optional[List[Index]] = None - """Lista resumida de índices relevantes (geralmente inclui IBOVESPA).""" + current_page: Optional[float] = FieldInfo(alias="currentPage", default=None) - items_per_page: Optional[int] = FieldInfo(alias="itemsPerPage", default=None) - """Número de itens (ativos) retornados por página (conforme `limit` ou padrão).""" + has_next_page: Optional[bool] = FieldInfo(alias="hasNextPage", default=None) - stocks: Optional[List[Stock]] = None - """Lista paginada e filtrada dos ativos solicitados.""" + items_per_page: Optional[float] = FieldInfo(alias="itemsPerPage", default=None) - total_count: Optional[int] = FieldInfo(alias="totalCount", default=None) - """ - Número total de ativos encontrados que correspondem aos filtros aplicados (sem - considerar a paginação). - """ + total_count: Optional[float] = FieldInfo(alias="totalCount", default=None) - total_pages: Optional[int] = FieldInfo(alias="totalPages", default=None) - """Número total de páginas existentes para a consulta/filtros aplicados.""" + total_pages: Optional[float] = FieldInfo(alias="totalPages", default=None) diff --git a/src/brapi/types/quote_retrieve_params.py b/src/brapi/types/quote_retrieve_params.py index e219ac0..27edbb1 100644 --- a/src/brapi/types/quote_retrieve_params.py +++ b/src/brapi/types/quote_retrieve_params.py @@ -2,112 +2,31 @@ from __future__ import annotations -from typing import List -from typing_extensions import Literal, TypedDict +from typing_extensions import Literal, Annotated, TypedDict + +from .._utils import PropertyInfo __all__ = ["QuoteRetrieveParams"] class QuoteRetrieveParams(TypedDict, total=False): token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ - - dividends: bool - """**Opcional.** Booleano (`true` ou `false`). - - Se `true`, inclui informações sobre dividendos e JCP (Juros sobre Capital - Próprio) pagos historicamente pelo ativo na chave `dividendsData`. - """ - - fundamental: bool - """**Opcional.** Booleano (`true` ou `false`). + """Token de autenticação (alternativa ao header Authorization)""" - Se `true`, inclui dados fundamentalistas básicos na resposta, como Preço/Lucro - (P/L) e Lucro Por Ação (LPA). + dividends: Literal["true", "false"] + """Incluir histórico de dividendos e JCP""" - **Nota:** Para dados fundamentalistas mais completos, utilize o parâmetro - `modules`. - """ + end_date: Annotated[str, PropertyInfo(alias="endDate")] + """Data final para dados históricos (formato YYYY-MM-DD)""" interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] - """ - **Opcional.** Define a granularidade (intervalo) dos dados históricos de preço - (`historicalDataPrice`). Requer que `range` também seja especificado. - - **Valores Possíveis:** - - - `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`: Intervalos intraday - (minutos/horas). **Atenção:** Disponibilidade pode variar conforme o `range` e - o ativo. - - `1d`: Diário (padrão se `range` for especificado e `interval` omitido). - - `5d`: 5 dias. - - `1wk`: Semanal. - - `1mo`: Mensal. - - `3mo`: Trimestral. - """ - - modules: List[ - Literal[ - "summaryProfile", - "balanceSheetHistory", - "defaultKeyStatistics", - "balanceSheetHistoryQuarterly", - "incomeStatementHistory", - "incomeStatementHistoryQuarterly", - "financialData", - "financialDataHistory", - "financialDataHistoryQuarterly", - "defaultKeyStatisticsHistory", - "defaultKeyStatisticsHistoryQuarterly", - "valueAddedHistory", - "valueAddedHistoryQuarterly", - "cashflowHistory", - "cashflowHistoryQuarterly", - ] - ] - """ - **Opcional.** Uma lista de módulos de dados adicionais, separados por vírgula - (`,`), para incluir na resposta. Permite buscar dados financeiros detalhados. - - **Exemplos:** - - - `modules=summaryProfile` (retorna perfil da empresa) - - `modules=balanceSheetHistory,incomeStatementHistory` (retorna histórico anual - do BP e DRE) - - Veja a descrição principal do endpoint para a lista completa de módulos e seus - conteúdos. - """ + """Intervalo/granularidade dos dados históricos""" - range: Literal["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] - """ - **Opcional.** Define o período para os dados históricos de preço - (`historicalDataPrice`). Se omitido, apenas a cotação mais recente é retornada - (a menos que `interval` seja usado). + modules: str + """Módulos de dados adicionais separados por vírgula""" - **Valores Possíveis:** + range: Literal["1d", "2d", "5d", "7d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] + """Período para dados históricos de preço""" - - `1d`: Último dia de pregão (intraday se `interval` for minutos/horas). - - `5d`: Últimos 5 dias. - - `1mo`: Último mês. - - `3mo`: Últimos 3 meses. - - `6mo`: Últimos 6 meses. - - `1y`: Último ano. - - `2y`: Últimos 2 anos. - - `5y`: Últimos 5 anos. - - `10y`: Últimos 10 anos. - - `ytd`: Desde o início do ano atual (Year-to-Date). - - `max`: Todo o período histórico disponível. - """ + start_date: Annotated[str, PropertyInfo(alias="startDate")] + """Data inicial para dados históricos (formato YYYY-MM-DD)""" diff --git a/src/brapi/types/quote_retrieve_response.py b/src/brapi/types/quote_retrieve_response.py index 9deefa1..cc2ad80 100644 --- a/src/brapi/types/quote_retrieve_response.py +++ b/src/brapi/types/quote_retrieve_response.py @@ -6,12 +6,8 @@ from pydantic import Field as FieldInfo from .._models import BaseModel -from .cashflow_entry import CashflowEntry -from .value_added_entry import ValueAddedEntry from .balance_sheet_entry import BalanceSheetEntry from .financial_data_entry import FinancialDataEntry -from .income_statement_entry import IncomeStatementEntry -from .default_key_statistics_entry import DefaultKeyStatisticsEntry __all__ = [ "QuoteRetrieveResponse", @@ -25,476 +21,310 @@ class ResultDividendsDataCashDividend(BaseModel): - """Detalhes sobre um pagamento de provento em dinheiro (Dividendo ou JCP).""" + approved_on: Optional[str] = FieldInfo(alias="approvedOn", default=None) + """Data de aprovação""" - approved_on: Optional[datetime] = FieldInfo(alias="approvedOn", default=None) - """Data em que o pagamento do provento foi aprovado pela empresa. + asset_issued: str = FieldInfo(alias="assetIssued") + """Código ISIN do ativo emissor""" - Pode ser uma estimativa em alguns casos. Formato ISO 8601. - """ - - asset_issued: Optional[str] = FieldInfo(alias="assetIssued", default=None) - """Ticker do ativo que pagou o provento (ex: `ITSA4`). - - Pode incluir sufixos específicos relacionados ao evento. - """ - - isin_code: Optional[str] = FieldInfo(alias="isinCode", default=None) - """ - Código ISIN (International Securities Identification Number) do ativo - relacionado ao provento. - """ + isin_code: str = FieldInfo(alias="isinCode") + """Código ISIN""" - label: Optional[str] = None - """Tipo do provento em dinheiro. + label: str + """Tipo (DIVIDENDO, JCP)""" - Geralmente `DIVIDENDO` ou `JCP` (Juros sobre Capital Próprio). - """ + last_date_prior: Optional[str] = FieldInfo(alias="lastDatePrior", default=None) + """Data-com (último dia antes da data ex)""" - last_date_prior: Optional[datetime] = FieldInfo(alias="lastDatePrior", default=None) - """Data Com (Ex-Date). + payment_date: Optional[str] = FieldInfo(alias="paymentDate", default=None) + """Data de pagamento""" - Último dia em que era necessário possuir o ativo para ter direito a receber este - provento. Pode ser uma estimativa. Formato ISO 8601. - """ + rate: float + """Valor por ação""" - payment_date: Optional[datetime] = FieldInfo(alias="paymentDate", default=None) - """Data efetiva em que o pagamento foi realizado (ou está previsto). + related_to: str = FieldInfo(alias="relatedTo") + """Período de referência""" - Formato ISO 8601. - """ - - rate: Optional[float] = None - """Valor bruto do provento pago por unidade do ativo (por ação, por cota).""" - - related_to: Optional[str] = FieldInfo(alias="relatedTo", default=None) - """ - Descrição do período ou evento ao qual o provento se refere (ex: - `1º Trimestre/2023`, `Resultado 2022`). - """ - - remarks: Optional[str] = None - """Observações adicionais ou informações relevantes sobre o provento.""" + remarks: str + """Observações""" class ResultDividendsDataStockDividend(BaseModel): - """ - Detalhes sobre um evento corporativo que afeta a quantidade de ações (Desdobramento/Split, Grupamento/Inplit, Bonificação). - """ + approved_on: Optional[str] = FieldInfo(alias="approvedOn", default=None) + """Data de aprovação""" - approved_on: Optional[datetime] = FieldInfo(alias="approvedOn", default=None) - """Data em que o evento foi aprovado. Formato ISO 8601.""" + asset_issued: str = FieldInfo(alias="assetIssued") + """Código ISIN do ativo emissor""" - asset_issued: Optional[str] = FieldInfo(alias="assetIssued", default=None) - """Ticker do ativo afetado pelo evento.""" + complete_factor: str = FieldInfo(alias="completeFactor") + """Fator completo (ex: 2 para 1)""" - complete_factor: Optional[str] = FieldInfo(alias="completeFactor", default=None) - """Descrição textual do fator (ex: `1 / 10`, `10 / 1`).""" + factor: float + """Fator do desdobramento/grupamento""" - factor: Optional[float] = None - """Fator numérico do evento. + isin_code: str = FieldInfo(alias="isinCode") + """Código ISIN""" - - **Bonificação:** Percentual (ex: 0.1 para 10%). - - **Desdobramento/Grupamento:** Fator multiplicativo ou divisor. - """ + label: str + """Tipo (DESDOBRAMENTO, GRUPAMENTO)""" - isin_code: Optional[str] = FieldInfo(alias="isinCode", default=None) - """Código ISIN do ativo.""" + last_date_prior: Optional[str] = FieldInfo(alias="lastDatePrior", default=None) + """Data de corte""" - label: Optional[str] = None - """Tipo do evento: `DESDOBRAMENTO`, `GRUPAMENTO`, `BONIFICACAO`.""" - - last_date_prior: Optional[datetime] = FieldInfo(alias="lastDatePrior", default=None) - """Data Com (Ex-Date). - - Último dia para possuir o ativo nas condições antigas. Formato ISO 8601. - """ - - remarks: Optional[str] = None - """Observações adicionais sobre o evento.""" + remarks: str + """Observações""" class ResultDividendsData(BaseModel): - """Objeto contendo informações sobre dividendos, JCP e outros eventos corporativos. - - Retornado apenas se `dividends=true` for especificado na requisição. - """ + """Dados de dividendos (quando dividends=true)""" - cash_dividends: Optional[List[ResultDividendsDataCashDividend]] = FieldInfo(alias="cashDividends", default=None) - """Lista de proventos pagos em dinheiro (Dividendos e JCP).""" + cash_dividends: List[ResultDividendsDataCashDividend] = FieldInfo(alias="cashDividends") + """Histórico de dividendos e JCP em dinheiro""" - stock_dividends: Optional[List[ResultDividendsDataStockDividend]] = FieldInfo(alias="stockDividends", default=None) - """Lista de eventos corporativos (Desdobramento, Grupamento, Bonificação).""" + stock_dividends: List[ResultDividendsDataStockDividend] = FieldInfo(alias="stockDividends") + """Histórico de bonificações e desdobramentos""" - subscriptions: Optional[List[object]] = None - """Lista de eventos de subscrição de ações (estrutura não detalhada aqui).""" + subscriptions: List[Optional[object]] + """Histórico de subscrições""" class ResultHistoricalDataPrice(BaseModel): - """Representa um ponto na série histórica de preços de um ativo.""" - - adjusted_close: Optional[float] = FieldInfo(alias="adjustedClose", default=None) + adjusted_close: float = FieldInfo(alias="adjustedClose") """ Preço de fechamento ajustado para proventos (dividendos, JCP, bonificações, etc.) e desdobramentos/grupamentos. """ - close: Optional[float] = None + close: float """Preço de fechamento do ativo no intervalo.""" - date: Optional[int] = None + date: int """ Data do pregão ou do ponto de dados, representada como um timestamp UNIX (número de segundos desde 1970-01-01 UTC). """ - high: Optional[float] = None + high: float """Preço máximo atingido pelo ativo no intervalo.""" - low: Optional[float] = None + low: float """Preço mínimo atingido pelo ativo no intervalo.""" - open: Optional[float] = None + open: float """Preço de abertura do ativo no intervalo (dia, semana, mês, etc.).""" - volume: Optional[int] = None + volume: int """Volume financeiro negociado no intervalo.""" class ResultSummaryProfile(BaseModel): - """Resumo do perfil da empresa. - - Retornado apenas se `modules` incluir `summaryProfile`. - """ + """Perfil da empresa (quando modules inclui summaryProfile)""" address1: Optional[str] = None - """Linha 1 do endereço da sede da empresa.""" + """Endereço linha 1""" address2: Optional[str] = None - """Linha 2 do endereço da sede da empresa (complemento).""" + """Endereço linha 2""" + + address3: Optional[str] = None + """Endereço linha 3""" city: Optional[str] = None - """Cidade da sede da empresa.""" + """Cidade""" - company_officers: Optional[List[object]] = FieldInfo(alias="companyOfficers", default=None) - """ - Lista de diretores e executivos principais da empresa (estrutura interna do - objeto não detalhada aqui). - """ + cnpj: Optional[str] = None + """CNPJ da empresa""" + + company_officers: List[Optional[object]] = FieldInfo(alias="companyOfficers") + """Diretoria""" country: Optional[str] = None - """País da sede da empresa.""" + """País""" - full_time_employees: Optional[int] = FieldInfo(alias="fullTimeEmployees", default=None) - """Número estimado de funcionários em tempo integral.""" + fax: Optional[str] = None + """Fax""" + + full_time_employees: Optional[float] = FieldInfo(alias="fullTimeEmployees", default=None) + """Número de funcionários""" industry: Optional[str] = None - """Nome da indústria em que a empresa atua.""" + """Setor""" industry_disp: Optional[str] = FieldInfo(alias="industryDisp", default=None) - """Nome de exibição formatado para a indústria.""" + """Nome do setor""" industry_key: Optional[str] = FieldInfo(alias="industryKey", default=None) - """Chave interna ou código para a indústria.""" + """Chave do setor""" long_business_summary: Optional[str] = FieldInfo(alias="longBusinessSummary", default=None) - """Descrição longa e detalhada sobre as atividades e o negócio da empresa.""" + """Descrição da empresa""" phone: Optional[str] = None - """Número de telefone principal da empresa.""" + """Telefone""" sector: Optional[str] = None - """Nome do setor de atuação da empresa.""" + """Segmento""" sector_disp: Optional[str] = FieldInfo(alias="sectorDisp", default=None) - """Nome de exibição formatado para o setor.""" + """Nome do segmento""" sector_key: Optional[str] = FieldInfo(alias="sectorKey", default=None) - """Chave interna ou código para o setor.""" + """Chave do segmento""" state: Optional[str] = None - """Estado ou província da sede da empresa.""" + """Estado""" + + symbol: str + """Ticker do ativo""" + + updated_at: Optional[str] = FieldInfo(alias="updatedAt", default=None) + """Data de atualização""" website: Optional[str] = None - """URL do website oficial da empresa.""" + """Website""" zip: Optional[str] = None - """Código Postal (CEP) da sede da empresa.""" + """CEP""" class Result(BaseModel): - """ - Contém os dados detalhados de um ativo específico retornado pelo endpoint `/api/quote/{tickers}`. - """ - average_daily_volume10_day: Optional[float] = FieldInfo(alias="averageDailyVolume10Day", default=None) - """Média do volume financeiro diário negociado nos últimos 10 dias.""" + """Média do volume diário nos últimos 10 dias""" average_daily_volume3_month: Optional[float] = FieldInfo(alias="averageDailyVolume3Month", default=None) - """Média do volume financeiro diário negociado nos últimos 3 meses.""" + """Média do volume diário nos últimos 3 meses""" - balance_sheet_history: Optional[List[BalanceSheetEntry]] = FieldInfo(alias="balanceSheetHistory", default=None) - """Histórico **anual** do Balanço Patrimonial. - - Retornado apenas se `modules` incluir `balanceSheetHistory`. - """ - - balance_sheet_history_quarterly: Optional[List[BalanceSheetEntry]] = FieldInfo( - alias="balanceSheetHistoryQuarterly", default=None - ) - """Histórico **trimestral** do Balanço Patrimonial. - - Retornado apenas se `modules` incluir `balanceSheetHistoryQuarterly`. - """ - - cashflow_history: Optional[List[CashflowEntry]] = FieldInfo(alias="cashflowHistory", default=None) - """Histórico **anual** da Demonstração do Fluxo de Caixa (DFC). - - Retornado apenas se `modules` incluir `cashflowHistory`. - """ - - cashflow_history_quarterly: Optional[List[CashflowEntry]] = FieldInfo( - alias="cashflowHistoryQuarterly", default=None - ) - """Histórico **trimestral** da Demonstração do Fluxo de Caixa (DFC). - - Retornado apenas se `modules` incluir `cashflowHistoryQuarterly`. - """ - - currency: Optional[str] = None - """Moeda na qual os valores monetários são expressos (geralmente `BRL`).""" - - default_key_statistics: Optional[DefaultKeyStatisticsEntry] = FieldInfo(alias="defaultKeyStatistics", default=None) - """Principais estatísticas financeiras atuais/TTM. - - Retornado apenas se `modules` incluir `defaultKeyStatistics`. - """ - - default_key_statistics_history: Optional[List[DefaultKeyStatisticsEntry]] = FieldInfo( - alias="defaultKeyStatisticsHistory", default=None - ) - """Histórico **anual** das principais estatísticas. - - Retornado apenas se `modules` incluir `defaultKeyStatisticsHistory`. - """ - - default_key_statistics_history_quarterly: Optional[List[DefaultKeyStatisticsEntry]] = FieldInfo( - alias="defaultKeyStatisticsHistoryQuarterly", default=None - ) - """Histórico **trimestral** das principais estatísticas. - - Retornado apenas se `modules` incluir `defaultKeyStatisticsHistoryQuarterly`. - """ - - dividends_data: Optional[ResultDividendsData] = FieldInfo(alias="dividendsData", default=None) - """Objeto contendo informações sobre dividendos, JCP e outros eventos corporativos. - - Retornado apenas se `dividends=true` for especificado na requisição. - """ + currency: str + """Moeda na qual os valores são expressos (geralmente BRL)""" earnings_per_share: Optional[float] = FieldInfo(alias="earningsPerShare", default=None) - """Lucro Por Ação (LPA) dos últimos 12 meses (TTM). - - Retornado se `fundamental=true`. - """ + """Lucro Por Ação (LPA) TTM""" fifty_two_week_high: Optional[float] = FieldInfo(alias="fiftyTwoWeekHigh", default=None) - """Preço máximo atingido nas últimas 52 semanas.""" + """Preço máximo nas últimas 52 semanas""" fifty_two_week_high_change: Optional[float] = FieldInfo(alias="fiftyTwoWeekHighChange", default=None) - """Variação absoluta entre o preço atual e o preço máximo das últimas 52 semanas.""" + """Variação entre preço atual e máximo de 52 semanas""" fifty_two_week_high_change_percent: Optional[float] = FieldInfo(alias="fiftyTwoWeekHighChangePercent", default=None) - """ - Variação percentual entre o preço atual e o preço máximo das últimas 52 semanas. - """ + """Variação percentual entre preço atual e máximo de 52 semanas""" fifty_two_week_low: Optional[float] = FieldInfo(alias="fiftyTwoWeekLow", default=None) - """Preço mínimo atingido nas últimas 52 semanas.""" + """Preço mínimo nas últimas 52 semanas""" fifty_two_week_low_change: Optional[float] = FieldInfo(alias="fiftyTwoWeekLowChange", default=None) - """Variação absoluta entre o preço atual e o preço mínimo das últimas 52 semanas.""" + """Variação entre preço atual e mínimo de 52 semanas""" fifty_two_week_range: Optional[str] = FieldInfo(alias="fiftyTwoWeekRange", default=None) - """ - String formatada mostrando o intervalo de preço das últimas 52 semanas (Mínimo - - Máximo). - """ - - financial_data: Optional[FinancialDataEntry] = FieldInfo(alias="financialData", default=None) - """Dados financeiros e indicadores TTM. - - Retornado apenas se `modules` incluir `financialData`. - """ - - financial_data_history: Optional[List[FinancialDataEntry]] = FieldInfo(alias="financialDataHistory", default=None) - """Histórico **anual** de dados financeiros e indicadores. - - Retornado apenas se `modules` incluir `financialDataHistory`. - """ - - financial_data_history_quarterly: Optional[List[FinancialDataEntry]] = FieldInfo( - alias="financialDataHistoryQuarterly", default=None - ) - """Histórico **trimestral** de dados financeiros e indicadores. - - Retornado apenas se `modules` incluir `financialDataHistoryQuarterly`. - """ - - historical_data_price: Optional[List[ResultHistoricalDataPrice]] = FieldInfo( - alias="historicalDataPrice", default=None - ) - """ - Array contendo a série histórica de preços, retornado apenas se os parâmetros - `range` e/ou `interval` forem especificados na requisição. - """ - - income_statement_history: Optional[List[IncomeStatementEntry]] = FieldInfo( - alias="incomeStatementHistory", default=None - ) - """Histórico **anual** da Demonstração do Resultado (DRE). - - Retornado apenas se `modules` incluir `incomeStatementHistory`. - """ - - income_statement_history_quarterly: Optional[List[IncomeStatementEntry]] = FieldInfo( - alias="incomeStatementHistoryQuarterly", default=None - ) - """Histórico **trimestral** da Demonstração do Resultado (DRE). - - Retornado apenas se `modules` incluir `incomeStatementHistoryQuarterly`. - """ + """Intervalo de preço das últimas 52 semanas""" logourl: Optional[str] = None - """URL da imagem do logo do ativo/empresa.""" + """URL do logo do ativo""" long_name: Optional[str] = FieldInfo(alias="longName", default=None) - """Nome longo ou completo da empresa ou ativo.""" + """Nome completo da empresa""" market_cap: Optional[float] = FieldInfo(alias="marketCap", default=None) - """Capitalização de mercado total do ativo (Preço Atual x Ações em Circulação).""" + """Capitalização de mercado total""" price_earnings: Optional[float] = FieldInfo(alias="priceEarnings", default=None) - """Indicador Preço/Lucro (P/L): Preço Atual / Lucro Por Ação (LPA) TTM. - - Retornado se `fundamental=true`. - """ + """Indicador Preço/Lucro (P/L)""" regular_market_change: Optional[float] = FieldInfo(alias="regularMarketChange", default=None) - """Variação absoluta do preço no dia atual em relação ao fechamento anterior.""" + """Variação absoluta do preço no dia em relação ao fechamento anterior""" regular_market_change_percent: Optional[float] = FieldInfo(alias="regularMarketChangePercent", default=None) - """Variação percentual do preço no dia atual em relação ao fechamento anterior.""" + """Variação percentual do preço no dia""" regular_market_day_high: Optional[float] = FieldInfo(alias="regularMarketDayHigh", default=None) - """Preço máximo atingido no dia de negociação atual.""" + """Preço máximo atingido no dia""" regular_market_day_low: Optional[float] = FieldInfo(alias="regularMarketDayLow", default=None) - """Preço mínimo atingido no dia de negociação atual.""" + """Preço mínimo atingido no dia""" regular_market_day_range: Optional[str] = FieldInfo(alias="regularMarketDayRange", default=None) - """String formatada mostrando o intervalo de preço do dia (Mínimo - Máximo).""" + """Intervalo de preço do dia (Mínimo - Máximo)""" regular_market_open: Optional[float] = FieldInfo(alias="regularMarketOpen", default=None) - """Preço de abertura no dia de negociação atual.""" + """Preço de abertura no dia""" regular_market_previous_close: Optional[float] = FieldInfo(alias="regularMarketPreviousClose", default=None) - """Preço de fechamento do pregão anterior.""" + """Preço de fechamento do pregão anterior""" regular_market_price: Optional[float] = FieldInfo(alias="regularMarketPrice", default=None) - """Preço atual ou do último negócio registrado.""" + """Preço atual ou do último negócio registrado""" - regular_market_time: Optional[datetime] = FieldInfo(alias="regularMarketTime", default=None) - """Data e hora da última atualização da cotação (último negócio registrado). - - Formato ISO 8601. - """ + regular_market_time: Optional[str] = FieldInfo(alias="regularMarketTime", default=None) + """Data/hora da última atualização da cotação (ISO 8601)""" regular_market_volume: Optional[float] = FieldInfo(alias="regularMarketVolume", default=None) - """Volume financeiro negociado no dia atual.""" + """Volume financeiro negociado no dia""" short_name: Optional[str] = FieldInfo(alias="shortName", default=None) - """Nome curto ou abreviado da empresa ou ativo.""" - - summary_profile: Optional[ResultSummaryProfile] = FieldInfo(alias="summaryProfile", default=None) - """Resumo do perfil da empresa. - - Retornado apenas se `modules` incluir `summaryProfile`. - """ + """Nome curto ou abreviado da empresa""" - symbol: Optional[str] = None - """Ticker (símbolo) do ativo (ex: `PETR4`, `^BVSP`).""" + symbol: str + """Ticker (símbolo) do ativo (ex: PETR4, ^BVSP)""" two_hundred_day_average: Optional[float] = FieldInfo(alias="twoHundredDayAverage", default=None) - """Média móvel simples dos preços de fechamento dos últimos 200 dias.""" + """Média móvel de 200 dias""" two_hundred_day_average_change: Optional[float] = FieldInfo(alias="twoHundredDayAverageChange", default=None) - """Variação absoluta entre o preço atual e a média de 200 dias.""" + """Variação entre preço atual e média de 200 dias""" two_hundred_day_average_change_percent: Optional[float] = FieldInfo( alias="twoHundredDayAverageChangePercent", default=None ) - """Variação percentual entre o preço atual e a média de 200 dias.""" - - updated_at: Optional[datetime] = FieldInfo(alias="updatedAt", default=None) - """ - Timestamp da última atualização dos dados do índice na fonte (aplicável - principalmente a índices, como `^BVSP`). Formato ISO 8601. - """ + """Variação percentual entre preço atual e média de 200 dias""" used_interval: Optional[str] = FieldInfo(alias="usedInterval", default=None) - """ - O intervalo (`interval`) efetivamente utilizado pela API para retornar os dados - históricos, caso solicitado. - """ + """Intervalo efetivamente utilizado para dados históricos""" used_range: Optional[str] = FieldInfo(alias="usedRange", default=None) - """ - O período (`range`) efetivamente utilizado pela API para retornar os dados - históricos, caso solicitado. - """ + """Período efetivamente utilizado para dados históricos""" - valid_intervals: Optional[List[str]] = FieldInfo(alias="validIntervals", default=None) - """ - Lista dos valores válidos que podem ser utilizados no parâmetro `interval` para - este ativo específico. - """ + balance_sheet_history: Optional[List[BalanceSheetEntry]] = FieldInfo(alias="balanceSheetHistory", default=None) + """Histórico anual do Balanço Patrimonial""" - valid_ranges: Optional[List[str]] = FieldInfo(alias="validRanges", default=None) - """ - Lista dos valores válidos que podem ser utilizados no parâmetro `range` para - este ativo específico. - """ + balance_sheet_history_quarterly: Optional[List[BalanceSheetEntry]] = FieldInfo( + alias="balanceSheetHistoryQuarterly", default=None + ) + """Histórico trimestral do Balanço Patrimonial""" - value_added_history: Optional[List[ValueAddedEntry]] = FieldInfo(alias="valueAddedHistory", default=None) - """Histórico **anual** da Demonstração do Valor Adicionado (DVA). + dividends_data: Optional[ResultDividendsData] = FieldInfo(alias="dividendsData", default=None) + """Dados de dividendos (quando dividends=true)""" - Retornado apenas se `modules` incluir `valueAddedHistory`. - """ + financial_data: Optional[FinancialDataEntry] = FieldInfo(alias="financialData", default=None) + """Dados financeiros e indicadores TTM""" + + financial_data_history: Optional[List[FinancialDataEntry]] = FieldInfo(alias="financialDataHistory", default=None) + """Histórico anual de dados financeiros""" - value_added_history_quarterly: Optional[List[ValueAddedEntry]] = FieldInfo( - alias="valueAddedHistoryQuarterly", default=None + financial_data_history_quarterly: Optional[List[FinancialDataEntry]] = FieldInfo( + alias="financialDataHistoryQuarterly", default=None ) - """Histórico **trimestral** da Demonstração do Valor Adicionado (DVA). + """Histórico trimestral de dados financeiros""" - Retornado apenas se `modules` incluir `valueAddedHistoryQuarterly`. - """ + historical_data_price: Optional[List[ResultHistoricalDataPrice]] = FieldInfo( + alias="historicalDataPrice", default=None + ) + """Série histórica de preços (quando range/interval fornecidos)""" + summary_profile: Optional[ResultSummaryProfile] = FieldInfo(alias="summaryProfile", default=None) + """Perfil da empresa (quando modules inclui summaryProfile)""" -class QuoteRetrieveResponse(BaseModel): - """Resposta principal do endpoint `/api/quote/{tickers}`.""" + valid_intervals: Optional[List[str]] = FieldInfo(alias="validIntervals", default=None) + """Valores válidos para o parâmetro interval""" - requested_at: Optional[datetime] = FieldInfo(alias="requestedAt", default=None) - """Timestamp indicando quando a requisição foi recebida pelo servidor. + valid_ranges: Optional[List[str]] = FieldInfo(alias="validRanges", default=None) + """Valores válidos para o parâmetro range""" - Formato ISO 8601. - """ - results: Optional[List[Result]] = None - """Array contendo os resultados detalhados para cada ticker solicitado.""" +class QuoteRetrieveResponse(BaseModel): + requested_at: datetime = FieldInfo(alias="requestedAt") + """Data e hora da requisição em formato ISO 8601""" - took: Optional[str] = None - """ - Tempo aproximado que o servidor levou para processar a requisição, em formato de - string (ex: `746ms`). - """ + results: List[Result] + + took: int + """Tempo de processamento em milissegundos""" diff --git a/src/brapi/types/v2/__init__.py b/src/brapi/types/v2/__init__.py index febc9e5..6fe0126 100644 --- a/src/brapi/types/v2/__init__.py +++ b/src/brapi/types/v2/__init__.py @@ -13,8 +13,6 @@ from .prime_rate_retrieve_response import PrimeRateRetrieveResponse as PrimeRateRetrieveResponse from .crypto_list_available_response import CryptoListAvailableResponse as CryptoListAvailableResponse from .currency_list_available_params import CurrencyListAvailableParams as CurrencyListAvailableParams -from .inflation_list_available_params import InflationListAvailableParams as InflationListAvailableParams from .currency_list_available_response import CurrencyListAvailableResponse as CurrencyListAvailableResponse -from .prime_rate_list_available_params import PrimeRateListAvailableParams as PrimeRateListAvailableParams from .inflation_list_available_response import InflationListAvailableResponse as InflationListAvailableResponse from .prime_rate_list_available_response import PrimeRateListAvailableResponse as PrimeRateListAvailableResponse diff --git a/src/brapi/types/v2/crypto_list_available_params.py b/src/brapi/types/v2/crypto_list_available_params.py index 0846d0d..5b36441 100644 --- a/src/brapi/types/v2/crypto_list_available_params.py +++ b/src/brapi/types/v2/crypto_list_available_params.py @@ -8,24 +8,5 @@ class CryptoListAvailableParams(TypedDict, total=False): - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ - search: str - """ - **Opcional.** Termo para filtrar a lista de siglas de criptomoedas - (correspondência parcial, case-insensitive). Se omitido, retorna todas as - siglas. - """ + """Filtrar criptomoedas por símbolo""" diff --git a/src/brapi/types/v2/crypto_list_available_response.py b/src/brapi/types/v2/crypto_list_available_response.py index d4dab7f..d41d9dd 100644 --- a/src/brapi/types/v2/crypto_list_available_response.py +++ b/src/brapi/types/v2/crypto_list_available_response.py @@ -1,6 +1,6 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -from typing import List, Optional +from typing import List from ..._models import BaseModel @@ -8,10 +8,4 @@ class CryptoListAvailableResponse(BaseModel): - """Resposta do endpoint que lista todas as criptomoedas disponíveis.""" - - coins: Optional[List[str]] = None - """ - Lista de siglas (tickers) das criptomoedas disponíveis (ex: `BTC`, `ETH`, - `LTC`). - """ + coins: List[str] diff --git a/src/brapi/types/v2/crypto_retrieve_params.py b/src/brapi/types/v2/crypto_retrieve_params.py index cbd226b..f10cc37 100644 --- a/src/brapi/types/v2/crypto_retrieve_params.py +++ b/src/brapi/types/v2/crypto_retrieve_params.py @@ -2,58 +2,20 @@ from __future__ import annotations -from typing_extensions import Literal, Required, TypedDict +from typing_extensions import TypedDict __all__ = ["CryptoRetrieveParams"] class CryptoRetrieveParams(TypedDict, total=False): - coin: Required[str] - """ - **Obrigatório.** Uma ou mais siglas (tickers) de criptomoedas que você deseja - consultar. Separe múltiplas siglas por vírgula (`,`). + coin: str + """Sigla(s) das criptomoedas separadas por vírgula""" - - **Exemplos:** `BTC`, `ETH,ADA`, `SOL`. - """ - - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + currency: str + """Moeda para cotação (padrão: BRL)""" - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ + interval: str + """Intervalo dos dados históricos""" - currency: str - """ - **Opcional.** A sigla da moeda fiduciária na qual a cotação da(s) criptomoeda(s) - deve ser retornada. Se omitido, o padrão é `BRL` (Real Brasileiro). - """ - - interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] - """ - **Opcional.** Define a granularidade (intervalo) dos dados históricos de preço - (`historicalDataPrice`). Requer que `range` também seja especificado. Funciona - de forma análoga ao endpoint de ações. - - - Valores: `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`, `1d`, `5d`, - `1wk`, `1mo`, `3mo`. - """ - - range: Literal["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"] - """ - **Opcional.** Define o período para os dados históricos de preço - (`historicalDataPrice`). Funciona de forma análoga ao endpoint de ações. Se - omitido, apenas a cotação mais recente é retornada (a menos que `interval` seja - usado). - - - Valores: `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, - `max`. - """ + range: str + """Período para dados históricos""" diff --git a/src/brapi/types/v2/crypto_retrieve_response.py b/src/brapi/types/v2/crypto_retrieve_response.py index 2b4ffa8..2e89b60 100644 --- a/src/brapi/types/v2/crypto_retrieve_response.py +++ b/src/brapi/types/v2/crypto_retrieve_response.py @@ -11,115 +11,68 @@ class CoinHistoricalDataPrice(BaseModel): - """Representa um ponto na série histórica de preços de uma criptomoeda.""" - adjusted_close: Optional[float] = FieldInfo(alias="adjustedClose", default=None) - """Preço de fechamento ajustado (geralmente igual ao `close` para cripto).""" close: Optional[float] = None - """Preço de fechamento da criptomoeda no intervalo.""" - date: Optional[int] = None - """Data do ponto de dados, representada como um timestamp UNIX.""" + date: int high: Optional[float] = None - """Preço máximo atingido no intervalo.""" low: Optional[float] = None - """Preço mínimo atingido no intervalo.""" open: Optional[float] = None - """Preço de abertura da criptomoeda no intervalo.""" - volume: Optional[int] = None - """ - Volume negociado no intervalo (na criptomoeda ou na moeda de referência, - verificar contexto). - """ + volume: Optional[float] = None class Coin(BaseModel): - """ - Contém os dados detalhados de uma criptomoeda específica retornada pelo endpoint `/api/v2/crypto`. - """ - - coin: Optional[str] = None - """Sigla (ticker) da criptomoeda (ex: `BTC`, `ETH`).""" - - coin_image_url: Optional[str] = FieldInfo(alias="coinImageUrl", default=None) - """URL da imagem do logo da criptomoeda.""" + coin: str - coin_name: Optional[str] = FieldInfo(alias="coinName", default=None) - """Nome completo da criptomoeda (ex: `Bitcoin`, `Ethereum`).""" + coin_name: str = FieldInfo(alias="coinName") - currency: Optional[str] = None - """Sigla da moeda fiduciária na qual os preços estão cotados (ex: `BRL`, `USD`).""" + currency: str - currency_rate_from_usd: Optional[float] = FieldInfo(alias="currencyRateFromUSD", default=None) - """Taxa de câmbio da `currency` em relação ao USD (Dólar Americano). + currency_rate_from_usd: float = FieldInfo(alias="currencyRateFromUSD") - `1 USD = X currency`. - """ + market_cap: float = FieldInfo(alias="marketCap") - historical_data_price: Optional[List[CoinHistoricalDataPrice]] = FieldInfo( - alias="historicalDataPrice", default=None - ) - """ - Array contendo a série histórica de preços, retornado se `range` ou `interval` - forem especificados. - """ + regular_market_change: float = FieldInfo(alias="regularMarketChange") - market_cap: Optional[int] = FieldInfo(alias="marketCap", default=None) - """Capitalização de mercado da criptomoeda na `currency` especificada.""" + regular_market_change_percent: float = FieldInfo(alias="regularMarketChangePercent") - regular_market_change: Optional[float] = FieldInfo(alias="regularMarketChange", default=None) - """Variação absoluta do preço nas últimas 24 horas (ou período relevante).""" + regular_market_day_high: float = FieldInfo(alias="regularMarketDayHigh") - regular_market_change_percent: Optional[float] = FieldInfo(alias="regularMarketChangePercent", default=None) - """Variação percentual do preço nas últimas 24 horas (ou período relevante).""" + regular_market_day_low: float = FieldInfo(alias="regularMarketDayLow") - regular_market_day_high: Optional[float] = FieldInfo(alias="regularMarketDayHigh", default=None) - """Preço máximo nas últimas 24 horas (ou período relevante).""" + regular_market_day_range: str = FieldInfo(alias="regularMarketDayRange") - regular_market_day_low: Optional[float] = FieldInfo(alias="regularMarketDayLow", default=None) - """Preço mínimo nas últimas 24 horas (ou período relevante).""" + regular_market_price: float = FieldInfo(alias="regularMarketPrice") - regular_market_day_range: Optional[str] = FieldInfo(alias="regularMarketDayRange", default=None) - """ - String formatada mostrando o intervalo de preço das últimas 24h (Mínimo - - Máximo). - """ + regular_market_time: str = FieldInfo(alias="regularMarketTime") - regular_market_price: Optional[float] = FieldInfo(alias="regularMarketPrice", default=None) - """Preço atual da criptomoeda na `currency` especificada.""" + regular_market_volume: float = FieldInfo(alias="regularMarketVolume") - regular_market_time: Optional[datetime] = FieldInfo(alias="regularMarketTime", default=None) - """Timestamp da última atualização da cotação. Formato ISO 8601.""" + coin_image_url: Optional[str] = FieldInfo(alias="coinImageUrl", default=None) - regular_market_volume: Optional[int] = FieldInfo(alias="regularMarketVolume", default=None) - """Volume negociado nas últimas 24 horas (na `currency` especificada).""" + historical_data_price: Optional[List[CoinHistoricalDataPrice]] = FieldInfo( + alias="historicalDataPrice", default=None + ) used_interval: Optional[str] = FieldInfo(alias="usedInterval", default=None) - """ - O intervalo (`interval`) efetivamente utilizado para os dados históricos, se - solicitado. - """ used_range: Optional[str] = FieldInfo(alias="usedRange", default=None) - """ - O período (`range`) efetivamente utilizado para os dados históricos, se - solicitado. - """ valid_intervals: Optional[List[str]] = FieldInfo(alias="validIntervals", default=None) - """Lista dos valores válidos para o parâmetro `interval` nesta criptomoeda.""" valid_ranges: Optional[List[str]] = FieldInfo(alias="validRanges", default=None) - """Lista dos valores válidos para o parâmetro `range` nesta criptomoeda.""" class CryptoRetrieveResponse(BaseModel): - """Resposta principal do endpoint `/api/v2/crypto`.""" + coins: List[Coin] + + requested_at: datetime = FieldInfo(alias="requestedAt") + """Data e hora da requisição em formato ISO 8601""" - coins: Optional[List[Coin]] = None - """Array contendo os resultados detalhados para cada criptomoeda solicitada.""" + took: int + """Tempo de processamento em milissegundos""" diff --git a/src/brapi/types/v2/currency_list_available_params.py b/src/brapi/types/v2/currency_list_available_params.py index 8ce9441..8b5a8f2 100644 --- a/src/brapi/types/v2/currency_list_available_params.py +++ b/src/brapi/types/v2/currency_list_available_params.py @@ -8,23 +8,5 @@ class CurrencyListAvailableParams(TypedDict, total=False): - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ - search: str - """ - **Opcional.** Termo para filtrar a lista pelo nome da moeda (correspondência - parcial, case-insensitive). - """ + """Filtrar pares de moedas por nome ou descrição""" diff --git a/src/brapi/types/v2/currency_list_available_response.py b/src/brapi/types/v2/currency_list_available_response.py index 0ceda29..3d85015 100644 --- a/src/brapi/types/v2/currency_list_available_response.py +++ b/src/brapi/types/v2/currency_list_available_response.py @@ -1,6 +1,6 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -from typing import List, Optional +from typing import List from ..._models import BaseModel @@ -8,19 +8,10 @@ class Currency(BaseModel): - currency: Optional[str] = None - """ - Nome da moeda ou par de moedas suportado (ex: `Dólar Americano/Real Brasileiro`, - `Euro/Real Brasileiro`). A sigla pode ser extraída deste nome ou consultada em - documentação adicional. - """ + currency: str + name: str -class CurrencyListAvailableResponse(BaseModel): - """Resposta do endpoint que lista todas as moedas fiduciárias disponíveis.""" - currencies: Optional[List[Currency]] = None - """ - Lista de objetos, cada um contendo o nome de uma moeda fiduciária ou par - suportado pela API. - """ +class CurrencyListAvailableResponse(BaseModel): + currencies: List[Currency] diff --git a/src/brapi/types/v2/currency_retrieve_params.py b/src/brapi/types/v2/currency_retrieve_params.py index 8ff1825..d8300ff 100644 --- a/src/brapi/types/v2/currency_retrieve_params.py +++ b/src/brapi/types/v2/currency_retrieve_params.py @@ -2,34 +2,11 @@ from __future__ import annotations -from typing_extensions import Required, TypedDict +from typing_extensions import TypedDict __all__ = ["CurrencyRetrieveParams"] class CurrencyRetrieveParams(TypedDict, total=False): - currency: Required[str] - """ - **Obrigatório.** Uma lista de um ou mais pares de moedas a serem consultados, - separados por vírgula (`,`). - - - **Formato:** `MOEDA_ORIGEM-MOEDA_DESTINO` (ex: `USD-BRL`). - - **Disponibilidade:** Consulte os pares válidos usando o endpoint - [`/api/v2/currency/available`](#/Moedas/getAvailableCurrencies). - - **Exemplo:** `USD-BRL,EUR-BRL,BTC-BRL` - """ - - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ + currency: str + """Par(es) de moedas separados por vírgula (ex: USD-BRL,EUR-BRL)""" diff --git a/src/brapi/types/v2/currency_retrieve_response.py b/src/brapi/types/v2/currency_retrieve_response.py index fdf3b33..54edf71 100644 --- a/src/brapi/types/v2/currency_retrieve_response.py +++ b/src/brapi/types/v2/currency_retrieve_response.py @@ -1,6 +1,7 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. from typing import List +from datetime import datetime from pydantic import Field as FieldInfo @@ -10,81 +11,34 @@ class Currency(BaseModel): - """ - Contém os dados detalhados da cotação de um **par de moedas fiduciárias específico**, retornado como um elemento do array `currency` no endpoint `/api/v2/currency`. - """ - ask_price: str = FieldInfo(alias="askPrice") - """ - **Preço de Venda (Ask):** Preço atual pelo qual o mercado está disposto a vender - a moeda de origem (`fromCurrency`) recebendo a moeda de destino (`toCurrency`). - Formato String. - """ bid_price: str = FieldInfo(alias="bidPrice") - """ - **Preço de Compra (Bid):** Preço atual pelo qual o mercado está disposto a - comprar a moeda de origem (`fromCurrency`) pagando com a moeda de destino - (`toCurrency`). Formato String. - """ bid_variation: str = FieldInfo(alias="bidVariation") - """ - **Variação Absoluta (Bid):** Mudança absoluta no preço de compra (bid) desde o - último fechamento ou período de referência. Formato String. - """ from_currency: str = FieldInfo(alias="fromCurrency") - """**Moeda de Origem:** Sigla da moeda base do par (ex: `USD` em `USD-BRL`).""" high: str - """ - **Máxima:** Preço mais alto atingido pelo par no período recente (geralmente - diário). Formato String. - """ low: str - """ - **Mínima:** Preço mais baixo atingido pelo par no período recente (geralmente - diário). Formato String. - """ name: str - """ - **Nome do Par:** Nome descritivo do par de moedas (ex: - `Dólar Americano/Real Brasileiro`). - """ percentage_change: str = FieldInfo(alias="percentageChange") - """ - **Variação Percentual:** Mudança percentual no preço do par desde o último - fechamento ou período de referência. Formato String. - """ to_currency: str = FieldInfo(alias="toCurrency") - """ - **Moeda de Destino:** Sigla da moeda de cotação do par (ex: `BRL` em `USD-BRL`). - """ updated_at_date: str = FieldInfo(alias="updatedAtDate") - """ - **Data da Atualização:** Data e hora da última atualização da cotação, formatada - de forma legível (`YYYY-MM-DD HH:MM:SS`). - """ updated_at_timestamp: str = FieldInfo(alias="updatedAtTimestamp") - """ - **Timestamp da Atualização:** Data e hora da última atualização da cotação, - representada como um **timestamp UNIX** (string contendo o número de segundos - desde 1970-01-01 UTC). - """ class CurrencyRetrieveResponse(BaseModel): - """Estrutura da **resposta principal** do endpoint `GET /api/v2/currency`.""" - currency: List[Currency] - """ - Array contendo os objetos `CurrencyQuote`, um para cada par de moeda válido - solicitado no parâmetro `currency`. - """ + + requested_at: datetime = FieldInfo(alias="requestedAt") + """Data e hora da requisição em formato ISO 8601""" + + took: int + """Tempo de processamento em milissegundos""" diff --git a/src/brapi/types/v2/inflation_list_available_params.py b/src/brapi/types/v2/inflation_list_available_params.py deleted file mode 100644 index 822dc76..0000000 --- a/src/brapi/types/v2/inflation_list_available_params.py +++ /dev/null @@ -1,30 +0,0 @@ -# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -from __future__ import annotations - -from typing_extensions import TypedDict - -__all__ = ["InflationListAvailableParams"] - - -class InflationListAvailableParams(TypedDict, total=False): - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ - - search: str - """ - **Opcional.** Termo para filtrar a lista pelo nome do país (correspondência - parcial, case-insensitive). Se omitido, retorna todos os países. - """ diff --git a/src/brapi/types/v2/inflation_list_available_response.py b/src/brapi/types/v2/inflation_list_available_response.py index 964adf4..eadb91a 100644 --- a/src/brapi/types/v2/inflation_list_available_response.py +++ b/src/brapi/types/v2/inflation_list_available_response.py @@ -1,6 +1,9 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -from typing import List, Optional +from typing import List +from datetime import datetime + +from pydantic import Field as FieldInfo from ..._models import BaseModel @@ -8,10 +11,9 @@ class InflationListAvailableResponse(BaseModel): - """Resposta do endpoint que lista os países com dados de inflação disponíveis.""" + countries: List[str] + + message: str - countries: Optional[List[str]] = None - """ - Lista de nomes de países (em minúsculas) para os quais há dados de inflação - disponíveis (ex: `brazil`, `usa`, `argentina`). - """ + requested_at: datetime = FieldInfo(alias="requestedAt") + """Data e hora da requisição em formato ISO 8601""" diff --git a/src/brapi/types/v2/inflation_retrieve_params.py b/src/brapi/types/v2/inflation_retrieve_params.py index 550be1e..3472d7e 100644 --- a/src/brapi/types/v2/inflation_retrieve_params.py +++ b/src/brapi/types/v2/inflation_retrieve_params.py @@ -2,9 +2,7 @@ from __future__ import annotations -from typing import Union -from datetime import date -from typing_extensions import Literal, Annotated, TypedDict +from typing_extensions import Annotated, TypedDict from ..._utils import PropertyInfo @@ -12,52 +10,17 @@ class InflationRetrieveParams(TypedDict, total=False): - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + end: str + """Data de fim (DD/MM/YYYY)""" - **Formas de Envio:** + historical: str + """Incluir dados históricos (true/false)""" - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + sort_by: Annotated[str, PropertyInfo(alias="sortBy")] + """Campo para ordenação (date ou value)""" - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ + sort_order: Annotated[str, PropertyInfo(alias="sortOrder")] + """Ordem de classificação (asc ou desc)""" - country: str - """**Opcional.** Nome do país para o qual buscar os dados de inflação. - - Use nomes em minúsculas. O padrão é `brazil`. Consulte - `/api/v2/inflation/available` para a lista de países suportados. - """ - - end: Annotated[Union[str, date], PropertyInfo(format="iso8601")] - """ - **Opcional.** Data final do período desejado para os dados históricos, no - formato `DD/MM/YYYY`. Requerido se `start` for especificado. - """ - - historical: bool - """**Opcional.** Booleano (`true` ou `false`). - - Define se dados históricos devem ser incluídos. O comportamento exato em - conjunto com `start`/`end` deve ser verificado. Padrão: `false`. - """ - - sort_by: Annotated[Literal["date", "value"], PropertyInfo(alias="sortBy")] - """**Opcional.** Campo pelo qual os resultados da inflação serão ordenados.""" - - sort_order: Annotated[Literal["asc", "desc"], PropertyInfo(alias="sortOrder")] - """**Opcional.** Direção da ordenação: `asc` (ascendente) ou `desc` (descendente). - - Padrão: `desc`. Requer que `sortBy` seja especificado. - """ - - start: Annotated[Union[str, date], PropertyInfo(format="iso8601")] - """ - **Opcional.** Data de início do período desejado para os dados históricos, no - formato `DD/MM/YYYY`. Requerido se `end` for especificado. - """ + start: str + """Data de início (DD/MM/YYYY)""" diff --git a/src/brapi/types/v2/inflation_retrieve_response.py b/src/brapi/types/v2/inflation_retrieve_response.py index a7daeaa..682a61a 100644 --- a/src/brapi/types/v2/inflation_retrieve_response.py +++ b/src/brapi/types/v2/inflation_retrieve_response.py @@ -1,6 +1,7 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -from typing import List, Optional +from typing import List +from datetime import datetime from pydantic import Field as FieldInfo @@ -10,29 +11,19 @@ class Inflation(BaseModel): - """Representa um ponto de dado histórico de inflação para um país.""" + date: str - date: Optional[str] = None - """Data da medição da inflação, no formato `DD/MM/YYYY`.""" + epoch_date: float = FieldInfo(alias="epochDate") - epoch_date: Optional[int] = FieldInfo(alias="epochDate", default=None) - """ - Timestamp UNIX (número de segundos desde 1970-01-01 UTC) correspondente à - `date`. - """ - - value: Optional[str] = None - """ - Valor do índice de inflação para a data especificada (formato string, pode - conter `%` ou ser apenas numérico). - """ + value: str + """Variação percentual do IPCA no mês""" class InflationRetrieveResponse(BaseModel): - """Resposta principal do endpoint `/api/v2/inflation`.""" + inflation: List[Inflation] + + requested_at: datetime = FieldInfo(alias="requestedAt") + """Data e hora da requisição em formato ISO 8601""" - inflation: Optional[List[Inflation]] = None - """ - Array contendo os registros históricos de inflação para o país e período - solicitados. - """ + took: int + """Tempo de processamento em milissegundos""" diff --git a/src/brapi/types/v2/prime_rate_list_available_params.py b/src/brapi/types/v2/prime_rate_list_available_params.py deleted file mode 100644 index a13a836..0000000 --- a/src/brapi/types/v2/prime_rate_list_available_params.py +++ /dev/null @@ -1,30 +0,0 @@ -# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -from __future__ import annotations - -from typing_extensions import TypedDict - -__all__ = ["PrimeRateListAvailableParams"] - - -class PrimeRateListAvailableParams(TypedDict, total=False): - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. - - **Formas de Envio:** - - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. - - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ - - search: str - """**Opcional.** Termo para filtrar a lista de países por nome. - - Retorna países cujos nomes contenham o termo especificado (case insensitive). - """ diff --git a/src/brapi/types/v2/prime_rate_list_available_response.py b/src/brapi/types/v2/prime_rate_list_available_response.py index 67e901a..c203877 100644 --- a/src/brapi/types/v2/prime_rate_list_available_response.py +++ b/src/brapi/types/v2/prime_rate_list_available_response.py @@ -1,6 +1,9 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -from typing import List, Optional +from typing import List +from datetime import datetime + +from pydantic import Field as FieldInfo from ..._models import BaseModel @@ -8,12 +11,9 @@ class PrimeRateListAvailableResponse(BaseModel): - """ - Resposta do endpoint `/api/v2/prime-rate/available` que lista os países disponíveis para consulta de taxa básica de juros (SELIC). - """ - - countries: Optional[List[str]] = None - """ - Lista de países com dados de taxa básica de juros (SELIC) disponíveis para - consulta. - """ + countries: List[str] + + message: str + + requested_at: datetime = FieldInfo(alias="requestedAt") + """Data e hora da requisição em formato ISO 8601""" diff --git a/src/brapi/types/v2/prime_rate_retrieve_params.py b/src/brapi/types/v2/prime_rate_retrieve_params.py index 0fb3d75..537f860 100644 --- a/src/brapi/types/v2/prime_rate_retrieve_params.py +++ b/src/brapi/types/v2/prime_rate_retrieve_params.py @@ -2,9 +2,7 @@ from __future__ import annotations -from typing import Union -from datetime import date -from typing_extensions import Literal, Annotated, TypedDict +from typing_extensions import Annotated, TypedDict from ..._utils import PropertyInfo @@ -12,56 +10,17 @@ class PrimeRateRetrieveParams(TypedDict, total=False): - token: str - """ - **Obrigatório caso não esteja adicionado como header "Authorization".** Seu - token de autenticação pessoal da API Brapi. + end: str + """Data de fim (DD/MM/YYYY)""" - **Formas de Envio:** + historical: str + """Incluir dados históricos (true/false)""" - 1. **Query Parameter:** Adicione `?token=SEU_TOKEN` ao final da URL. - 2. **HTTP Header:** Inclua o header `Authorization: Bearer SEU_TOKEN` na sua - requisição. + sort_by: Annotated[str, PropertyInfo(alias="sortBy")] + """Campo para ordenação (date ou value)""" - Ambos os métodos são aceitos, mas pelo menos um deles deve ser utilizado. - Obtenha seu token em [brapi.dev/dashboard](https://brapi.dev/dashboard). - """ + sort_order: Annotated[str, PropertyInfo(alias="sortOrder")] + """Ordem de classificação (asc ou desc)""" - country: str - """ - **Opcional.** O país do qual você deseja obter informações sobre a taxa básica - de juros. Por padrão, o país é definido como brazil. Você pode consultar a lista - de países disponíveis através do endpoint `/api/v2/prime-rate/available`. - """ - - end: Annotated[Union[str, date], PropertyInfo(format="iso8601")] - """**Opcional.** Data final do período para busca no formato DD/MM/YYYY. - - Por padrão é a data atual. Útil quando `historical=true` para restringir o - período da série histórica. - """ - - historical: bool - """**Opcional.** Define se os dados históricos serão retornados. - - Se definido como `true`, retorna a série histórica completa. Se `false` (padrão) - ou omitido, retorna apenas o valor mais recente. - """ - - sort_by: Annotated[Literal["date", "value"], PropertyInfo(alias="sortBy")] - """**Opcional.** Campo pelo qual os resultados serão ordenados. - - Por padrão, ordena por `date` (data). - """ - - sort_order: Annotated[Literal["asc", "desc"], PropertyInfo(alias="sortOrder")] - """ - **Opcional.** Define se a ordenação será crescente (`asc`) ou decrescente - (`desc`). Por padrão, é `desc` (decrescente). - """ - - start: Annotated[Union[str, date], PropertyInfo(format="iso8601")] - """**Opcional.** Data inicial do período para busca no formato DD/MM/YYYY. - - Útil quando `historical=true` para restringir o período da série histórica. - """ + start: str + """Data de início (DD/MM/YYYY)""" diff --git a/src/brapi/types/v2/prime_rate_retrieve_response.py b/src/brapi/types/v2/prime_rate_retrieve_response.py index b4e9a78..8152987 100644 --- a/src/brapi/types/v2/prime_rate_retrieve_response.py +++ b/src/brapi/types/v2/prime_rate_retrieve_response.py @@ -1,6 +1,7 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -from typing import List, Optional +from typing import List +from datetime import datetime from pydantic import Field as FieldInfo @@ -10,25 +11,19 @@ class PrimeRate(BaseModel): - """ - Representa um registro individual de taxa básica de juros (SELIC) para uma data específica. - """ + date: str - date: Optional[str] = None - """Data do registro no formato DD/MM/YYYY.""" + epoch_date: float = FieldInfo(alias="epochDate") - epoch_date: Optional[int] = FieldInfo(alias="epochDate", default=None) - """Timestamp em milissegundos (formato epoch) correspondente à data do registro.""" - - value: Optional[str] = None - """Valor da taxa básica de juros (SELIC) para a data correspondente.""" + value: str + """Taxa SELIC meta anualizada (% a.a.)""" class PrimeRateRetrieveResponse(BaseModel): - """Resposta principal do endpoint `/api/v2/prime-rate`.""" + prime_rate: List[PrimeRate] = FieldInfo(alias="prime-rate") + + requested_at: datetime = FieldInfo(alias="requestedAt") + """Data e hora da requisição em formato ISO 8601""" - prime_rate: Optional[List[PrimeRate]] = FieldInfo(alias="prime-rate", default=None) - """ - Array contendo os registros históricos de taxa básica de juros (SELIC) para o - país e período solicitados. - """ + took: int + """Tempo de processamento em milissegundos""" diff --git a/src/brapi/types/value_added_entry.py b/src/brapi/types/value_added_entry.py deleted file mode 100644 index b553683..0000000 --- a/src/brapi/types/value_added_entry.py +++ /dev/null @@ -1,244 +0,0 @@ -# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -from typing import Optional -from datetime import date -from typing_extensions import Literal - -from pydantic import Field as FieldInfo - -from .._models import BaseModel - -__all__ = ["ValueAddedEntry"] - - -class ValueAddedEntry(BaseModel): - """ - Representa os dados de uma Demonstração do Valor Adicionado (DVA) para um período específico (anual ou trimestral). A DVA mostra como a riqueza gerada pela empresa foi distribuída. - """ - - added_value_received_by_transfer: Optional[float] = FieldInfo(alias="addedValueReceivedByTransfer", default=None) - """ - Valor Adicionado Recebido em Transferência (Resultado de Equivalência - Patrimonial, Receitas Financeiras, etc.). Item 6 da DVA. - """ - - added_value_received_on_transfer: Optional[float] = FieldInfo(alias="addedValueReceivedOnTransfer", default=None) - """ - Valor Adicionado Recebido em Transferência (sinônimo de - `addedValueReceivedByTransfer`). - """ - - added_value_to_distribute: Optional[float] = FieldInfo(alias="addedValueToDistribute", default=None) - """ - Valor Adicionado Total a Distribuir (Líquido Produzido + Recebido em - Transferência). Item 7 da DVA. - """ - - claims_and_benefits: Optional[float] = FieldInfo(alias="claimsAndBenefits", default=None) - """Sinistros Retidos e Benefícios.""" - - complementary_pension_operations_revenue: Optional[float] = FieldInfo( - alias="complementaryPensionOperationsRevenue", default=None - ) - """Receita com Operações de Previdência Complementar.""" - - construction_of_own_assets: Optional[float] = FieldInfo(alias="constructionOfOwnAssets", default=None) - """Construção de Ativos Próprios.""" - - costs_with_products_sold: Optional[float] = FieldInfo(alias="costsWithProductsSold", default=None) - """Custos dos Produtos, Mercadorias e Serviços Vendidos (detalhamento).""" - - depreciation_and_amortization: Optional[float] = FieldInfo(alias="depreciationAndAmortization", default=None) - """Depreciação e Amortização.""" - - distribution_of_added_value: Optional[float] = FieldInfo(alias="distributionOfAddedValue", default=None) - """Distribuição do Valor Adicionado (Soma dos itens seguintes). Item 8 da DVA.""" - - dividends: Optional[float] = None - """Dividendos Distribuídos.""" - - end_date: Optional[date] = FieldInfo(alias="endDate", default=None) - """Data de término do período fiscal ao qual a DVA se refere (YYYY-MM-DD).""" - - equity_income_result: Optional[float] = FieldInfo(alias="equityIncomeResult", default=None) - """Resultado de Equivalência Patrimonial (como receita na DVA).""" - - equity_remuneration: Optional[float] = FieldInfo(alias="equityRemuneration", default=None) - """Remuneração de Capitais Próprios (JCP, Dividendos, Lucros Retidos).""" - - federal_taxes: Optional[float] = FieldInfo(alias="federalTaxes", default=None) - """Impostos Federais (IRPJ, CSLL, PIS, COFINS, IPI).""" - - fees_revenue: Optional[float] = FieldInfo(alias="feesRevenue", default=None) - """Receita com Taxas e Comissões.""" - - financial_income: Optional[float] = FieldInfo(alias="financialIncome", default=None) - """Receitas Financeiras (como valor recebido em transferência).""" - - financial_intermediation_expenses: Optional[float] = FieldInfo( - alias="financialIntermediationExpenses", default=None - ) - """Despesas de Intermediação Financeira (específico para bancos).""" - - financial_intermediation_revenue: Optional[float] = FieldInfo(alias="financialIntermediationRevenue", default=None) - """Receita de Intermediação Financeira (específico para bancos).""" - - gross_added_value: Optional[float] = FieldInfo(alias="grossAddedValue", default=None) - """Valor Adicionado Bruto (Receitas - Insumos). Item 3 da DVA.""" - - insurance_operations_revenue: Optional[float] = FieldInfo(alias="insuranceOperationsRevenue", default=None) - """Receita com Operações de Seguros (específico para Seguradoras).""" - - insurance_operations_variations: Optional[float] = FieldInfo(alias="insuranceOperationsVariations", default=None) - """Variações de Operações de Seguros.""" - - interest_on_own_equity: Optional[float] = FieldInfo(alias="interestOnOwnEquity", default=None) - """Juros sobre o Capital Próprio (JCP).""" - - loss_or_recovery_of_assets: Optional[float] = FieldInfo(alias="lossOrRecoveryOfAssets", default=None) - """Perda/Recuperação de Valores de Ativos (Impairment - como custo/receita).""" - - loss_or_recovery_of_asset_values: Optional[float] = FieldInfo(alias="lossOrRecoveryOfAssetValues", default=None) - """Perda / Recuperação de Valores de Ativos (Impairment).""" - - materials_energy_and_others: Optional[float] = FieldInfo(alias="materialsEnergyAndOthers", default=None) - """Custos com Materiais, Energia, Serviços de Terceiros e Outros.""" - - municipal_taxes: Optional[float] = FieldInfo(alias="municipalTaxes", default=None) - """Impostos Municipais (ISS).""" - - net_added_value: Optional[float] = FieldInfo(alias="netAddedValue", default=None) - """Valor Adicionado Líquido Produzido pela Entidade (Bruto - Retenções). - - Item 5 da DVA. - """ - - net_added_value_produced: Optional[float] = FieldInfo(alias="netAddedValueProduced", default=None) - """Valor Adicionado Líquido Produzido (sinônimo de `netAddedValue`).""" - - net_operating_revenue: Optional[float] = FieldInfo(alias="netOperatingRevenue", default=None) - """Receita Operacional Líquida (detalhamento).""" - - non_controlling_share_of_retained_earnings: Optional[float] = FieldInfo( - alias="nonControllingShareOfRetainedEarnings", default=None - ) - """Participação dos Não Controladores nos Lucros Retidos.""" - - other_distributions: Optional[float] = FieldInfo(alias="otherDistributions", default=None) - """Outras Distribuições.""" - - other_retentions: Optional[float] = FieldInfo(alias="otherRetentions", default=None) - """Outras Retenções (Exaustão, etc.).""" - - other_revenues: Optional[float] = FieldInfo(alias="otherRevenues", default=None) - """Outras Receitas.""" - - other_supplies: Optional[float] = FieldInfo(alias="otherSupplies", default=None) - """Outros Insumos.""" - - other_values_received_by_transfer: Optional[float] = FieldInfo(alias="otherValuesReceivedByTransfer", default=None) - """Outros Valores Recebidos (Receitas Financeiras, Aluguéis, etc.).""" - - other_variations: Optional[float] = FieldInfo(alias="otherVariations", default=None) - """Outras Variações.""" - - own_equity_remuneration: Optional[float] = FieldInfo(alias="ownEquityRemuneration", default=None) - """Remuneração de Capitais Próprios (sinônimo de `equityRemuneration`).""" - - pension_operations_variations: Optional[float] = FieldInfo(alias="pensionOperationsVariations", default=None) - """Variações de Operações de Previdência.""" - - product_sales: Optional[float] = FieldInfo(alias="productSales", default=None) - """Venda de Produtos e Serviços (detalhamento).""" - - provision_or_reversal_of_doubtful_accounts: Optional[float] = FieldInfo( - alias="provisionOrReversalOfDoubtfulAccounts", default=None - ) - """ - Provisão/Reversão para Créditos de Liquidação Duvidosa (PCLD - como - receita/despesa na DVA). - """ - - provision_or_reversal_of_expected_credit_risk_losses: Optional[float] = FieldInfo( - alias="provisionOrReversalOfExpectedCreditRiskLosses", default=None - ) - """Provisão/Reversão de Perdas com Risco de Crédito (PCLD).""" - - remuneration_of_third_party_capitals: Optional[float] = FieldInfo( - alias="remunerationOfThirdPartyCapitals", default=None - ) - """Remuneração de Capitais de Terceiros (Juros, Aluguéis).""" - - result_of_coinsurance_operations_assigned: Optional[float] = FieldInfo( - alias="resultOfCoinsuranceOperationsAssigned", default=None - ) - """Resultado de Operações de Cosseguros Cedidos.""" - - results_of_ceded_reinsurance_operations: Optional[float] = FieldInfo( - alias="resultsOfCededReinsuranceOperations", default=None - ) - """Resultados de Operações de Resseguros Cedidos.""" - - retained_earnings_or_loss: Optional[float] = FieldInfo(alias="retainedEarningsOrLoss", default=None) - """Lucros Retidos ou Prejuízo do Exercício.""" - - retentions: Optional[float] = None - """Retenções (Depreciação, Amortização e Exaustão). Item 4 da DVA.""" - - revenue: Optional[float] = None - """Receitas (Venda de Mercadorias, Produtos e Serviços, etc.). Item 1 da DVA.""" - - revenue_from_the_provision_of_services: Optional[float] = FieldInfo( - alias="revenueFromTheProvisionOfServices", default=None - ) - """Receita da Prestação de Serviços (detalhamento).""" - - services: Optional[float] = None - """Serviços de Terceiros (detalhamento).""" - - state_taxes: Optional[float] = FieldInfo(alias="stateTaxes", default=None) - """Impostos Estaduais (ICMS).""" - - supplies_purchased_from_third_parties: Optional[float] = FieldInfo( - alias="suppliesPurchasedFromThirdParties", default=None - ) - """Insumos Adquiridos de Terceiros (Custo de Mercadorias, Matérias-Primas). - - Item 2 da DVA. - """ - - symbol: Optional[str] = None - """Ticker do ativo ao qual a DVA se refere.""" - - taxes: Optional[float] = None - """Impostos, Taxas e Contribuições (Federais, Estaduais, Municipais).""" - - team_remuneration: Optional[float] = FieldInfo(alias="teamRemuneration", default=None) - """Pessoal e Encargos (Salários, Benefícios, FGTS).""" - - third_party_materials_and_services: Optional[float] = FieldInfo( - alias="thirdPartyMaterialsAndServices", default=None - ) - """Materiais, Energia, Serviços de Terceiros.""" - - total_added_value_to_distribute: Optional[float] = FieldInfo(alias="totalAddedValueToDistribute", default=None) - """Valor Adicionado Total a Distribuir (sinônimo de `addedValueToDistribute`).""" - - type: Optional[Literal["yearly", "quarterly"]] = None - """Indica a periodicidade da DVA: `yearly` (anual) ou `quarterly` (trimestral).""" - - updated_at: Optional[date] = FieldInfo(alias="updatedAt", default=None) - """ - Data da última atualização deste registro específico na fonte de dados - (YYYY-MM-DD). - """ - - variation_in_deferred_selling_expenses: Optional[float] = FieldInfo( - alias="variationInDeferredSellingExpenses", default=None - ) - """Variação nas Despesas de Comercialização Diferidas.""" - - variations_of_technical_provisions: Optional[float] = FieldInfo( - alias="variationsOfTechnicalProvisions", default=None - ) - """Variações das Provisões Técnicas (específico para Seguradoras).""" diff --git a/tests/api_resources/test_available.py b/tests/api_resources/test_available.py index 6b366e0..0821dab 100644 --- a/tests/api_resources/test_available.py +++ b/tests/api_resources/test_available.py @@ -17,22 +17,21 @@ class TestAvailable: parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list(self, client: Brapi) -> None: available = client.available.list() assert_matches_type(AvailableListResponse, available, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list_with_all_params(self, client: Brapi) -> None: available = client.available.list( - token="token", - search="search", + search="PETR", ) assert_matches_type(AvailableListResponse, available, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_list(self, client: Brapi) -> None: response = client.available.with_raw_response.list() @@ -42,7 +41,7 @@ def test_raw_response_list(self, client: Brapi) -> None: available = response.parse() assert_matches_type(AvailableListResponse, available, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_list(self, client: Brapi) -> None: with client.available.with_streaming_response.list() as response: @@ -60,22 +59,21 @@ class TestAsyncAvailable: "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"] ) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list(self, async_client: AsyncBrapi) -> None: available = await async_client.available.list() assert_matches_type(AvailableListResponse, available, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list_with_all_params(self, async_client: AsyncBrapi) -> None: available = await async_client.available.list( - token="token", - search="search", + search="PETR", ) assert_matches_type(AvailableListResponse, available, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_list(self, async_client: AsyncBrapi) -> None: response = await async_client.available.with_raw_response.list() @@ -85,7 +83,7 @@ async def test_raw_response_list(self, async_client: AsyncBrapi) -> None: available = await response.parse() assert_matches_type(AvailableListResponse, available, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_list(self, async_client: AsyncBrapi) -> None: async with async_client.available.with_streaming_response.list() as response: diff --git a/tests/api_resources/test_quote.py b/tests/api_resources/test_quote.py index 21a14a6..eced03c 100644 --- a/tests/api_resources/test_quote.py +++ b/tests/api_resources/test_quote.py @@ -17,33 +17,34 @@ class TestQuote: parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve(self, client: Brapi) -> None: quote = client.quote.retrieve( - tickers="PETR4,MGLU3", + tickers="PETR4,VALE3", ) assert_matches_type(QuoteRetrieveResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve_with_all_params(self, client: Brapi) -> None: quote = client.quote.retrieve( - tickers="PETR4,MGLU3", + tickers="PETR4,VALE3", token="token", - dividends=True, - fundamental=True, - interval="1d", - modules=["summaryProfile", "balanceSheetHistory", "financialData"], - range="5d", + dividends="true", + end_date="2024-12-31", + interval="1m", + modules="summaryProfile,balanceSheetHistory,financialData", + range="1d", + start_date="2024-01-01", ) assert_matches_type(QuoteRetrieveResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_retrieve(self, client: Brapi) -> None: response = client.quote.with_raw_response.retrieve( - tickers="PETR4,MGLU3", + tickers="PETR4,VALE3", ) assert response.is_closed is True @@ -51,11 +52,11 @@ def test_raw_response_retrieve(self, client: Brapi) -> None: quote = response.parse() assert_matches_type(QuoteRetrieveResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_retrieve(self, client: Brapi) -> None: with client.quote.with_streaming_response.retrieve( - tickers="PETR4,MGLU3", + tickers="PETR4,VALE3", ) as response: assert not response.is_closed assert response.http_request.headers.get("X-Stainless-Lang") == "python" @@ -65,7 +66,7 @@ def test_streaming_response_retrieve(self, client: Brapi) -> None: assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_path_params_retrieve(self, client: Brapi) -> None: with pytest.raises(ValueError, match=r"Expected a non-empty value for `tickers` but received ''"): @@ -73,28 +74,28 @@ def test_path_params_retrieve(self, client: Brapi) -> None: tickers="", ) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list(self, client: Brapi) -> None: quote = client.quote.list() assert_matches_type(QuoteListResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list_with_all_params(self, client: Brapi) -> None: quote = client.quote.list( token="token", - limit=1, - page=1, + limit="limit", + page="page", search="search", - sector="Retail Trade", + sector="sector", sort_by="name", sort_order="asc", type="stock", ) assert_matches_type(QuoteListResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_list(self, client: Brapi) -> None: response = client.quote.with_raw_response.list() @@ -104,7 +105,7 @@ def test_raw_response_list(self, client: Brapi) -> None: quote = response.parse() assert_matches_type(QuoteListResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_list(self, client: Brapi) -> None: with client.quote.with_streaming_response.list() as response: @@ -122,33 +123,34 @@ class TestAsyncQuote: "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"] ) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve(self, async_client: AsyncBrapi) -> None: quote = await async_client.quote.retrieve( - tickers="PETR4,MGLU3", + tickers="PETR4,VALE3", ) assert_matches_type(QuoteRetrieveResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve_with_all_params(self, async_client: AsyncBrapi) -> None: quote = await async_client.quote.retrieve( - tickers="PETR4,MGLU3", + tickers="PETR4,VALE3", token="token", - dividends=True, - fundamental=True, - interval="1d", - modules=["summaryProfile", "balanceSheetHistory", "financialData"], - range="5d", + dividends="true", + end_date="2024-12-31", + interval="1m", + modules="summaryProfile,balanceSheetHistory,financialData", + range="1d", + start_date="2024-01-01", ) assert_matches_type(QuoteRetrieveResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_retrieve(self, async_client: AsyncBrapi) -> None: response = await async_client.quote.with_raw_response.retrieve( - tickers="PETR4,MGLU3", + tickers="PETR4,VALE3", ) assert response.is_closed is True @@ -156,11 +158,11 @@ async def test_raw_response_retrieve(self, async_client: AsyncBrapi) -> None: quote = await response.parse() assert_matches_type(QuoteRetrieveResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> None: async with async_client.quote.with_streaming_response.retrieve( - tickers="PETR4,MGLU3", + tickers="PETR4,VALE3", ) as response: assert not response.is_closed assert response.http_request.headers.get("X-Stainless-Lang") == "python" @@ -170,7 +172,7 @@ async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> No assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_path_params_retrieve(self, async_client: AsyncBrapi) -> None: with pytest.raises(ValueError, match=r"Expected a non-empty value for `tickers` but received ''"): @@ -178,28 +180,28 @@ async def test_path_params_retrieve(self, async_client: AsyncBrapi) -> None: tickers="", ) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list(self, async_client: AsyncBrapi) -> None: quote = await async_client.quote.list() assert_matches_type(QuoteListResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list_with_all_params(self, async_client: AsyncBrapi) -> None: quote = await async_client.quote.list( token="token", - limit=1, - page=1, + limit="limit", + page="page", search="search", - sector="Retail Trade", + sector="sector", sort_by="name", sort_order="asc", type="stock", ) assert_matches_type(QuoteListResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_list(self, async_client: AsyncBrapi) -> None: response = await async_client.quote.with_raw_response.list() @@ -209,7 +211,7 @@ async def test_raw_response_list(self, async_client: AsyncBrapi) -> None: quote = await response.parse() assert_matches_type(QuoteListResponse, quote, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_list(self, async_client: AsyncBrapi) -> None: async with async_client.quote.with_streaming_response.list() as response: diff --git a/tests/api_resources/v2/test_crypto.py b/tests/api_resources/v2/test_crypto.py index 957328e..0d1cf4d 100644 --- a/tests/api_resources/v2/test_crypto.py +++ b/tests/api_resources/v2/test_crypto.py @@ -20,44 +20,37 @@ class TestCrypto: parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve(self, client: Brapi) -> None: - crypto = client.v2.crypto.retrieve( - coin="coin", - ) + crypto = client.v2.crypto.retrieve() assert_matches_type(CryptoRetrieveResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve_with_all_params(self, client: Brapi) -> None: crypto = client.v2.crypto.retrieve( - coin="coin", - token="token", - currency="currency", - interval="1m", - range="1d", + coin="BTC,ETH", + currency="BRL", + interval="interval", + range="range", ) assert_matches_type(CryptoRetrieveResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_retrieve(self, client: Brapi) -> None: - response = client.v2.crypto.with_raw_response.retrieve( - coin="coin", - ) + response = client.v2.crypto.with_raw_response.retrieve() assert response.is_closed is True assert response.http_request.headers.get("X-Stainless-Lang") == "python" crypto = response.parse() assert_matches_type(CryptoRetrieveResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_retrieve(self, client: Brapi) -> None: - with client.v2.crypto.with_streaming_response.retrieve( - coin="coin", - ) as response: + with client.v2.crypto.with_streaming_response.retrieve() as response: assert not response.is_closed assert response.http_request.headers.get("X-Stainless-Lang") == "python" @@ -66,22 +59,21 @@ def test_streaming_response_retrieve(self, client: Brapi) -> None: assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list_available(self, client: Brapi) -> None: crypto = client.v2.crypto.list_available() assert_matches_type(CryptoListAvailableResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list_available_with_all_params(self, client: Brapi) -> None: crypto = client.v2.crypto.list_available( - token="token", - search="search", + search="BTC", ) assert_matches_type(CryptoListAvailableResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_list_available(self, client: Brapi) -> None: response = client.v2.crypto.with_raw_response.list_available() @@ -91,7 +83,7 @@ def test_raw_response_list_available(self, client: Brapi) -> None: crypto = response.parse() assert_matches_type(CryptoListAvailableResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_list_available(self, client: Brapi) -> None: with client.v2.crypto.with_streaming_response.list_available() as response: @@ -109,44 +101,37 @@ class TestAsyncCrypto: "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"] ) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve(self, async_client: AsyncBrapi) -> None: - crypto = await async_client.v2.crypto.retrieve( - coin="coin", - ) + crypto = await async_client.v2.crypto.retrieve() assert_matches_type(CryptoRetrieveResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve_with_all_params(self, async_client: AsyncBrapi) -> None: crypto = await async_client.v2.crypto.retrieve( - coin="coin", - token="token", - currency="currency", - interval="1m", - range="1d", + coin="BTC,ETH", + currency="BRL", + interval="interval", + range="range", ) assert_matches_type(CryptoRetrieveResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_retrieve(self, async_client: AsyncBrapi) -> None: - response = await async_client.v2.crypto.with_raw_response.retrieve( - coin="coin", - ) + response = await async_client.v2.crypto.with_raw_response.retrieve() assert response.is_closed is True assert response.http_request.headers.get("X-Stainless-Lang") == "python" crypto = await response.parse() assert_matches_type(CryptoRetrieveResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> None: - async with async_client.v2.crypto.with_streaming_response.retrieve( - coin="coin", - ) as response: + async with async_client.v2.crypto.with_streaming_response.retrieve() as response: assert not response.is_closed assert response.http_request.headers.get("X-Stainless-Lang") == "python" @@ -155,22 +140,21 @@ async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> No assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list_available(self, async_client: AsyncBrapi) -> None: crypto = await async_client.v2.crypto.list_available() assert_matches_type(CryptoListAvailableResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list_available_with_all_params(self, async_client: AsyncBrapi) -> None: crypto = await async_client.v2.crypto.list_available( - token="token", - search="search", + search="BTC", ) assert_matches_type(CryptoListAvailableResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> None: response = await async_client.v2.crypto.with_raw_response.list_available() @@ -180,7 +164,7 @@ async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> No crypto = await response.parse() assert_matches_type(CryptoListAvailableResponse, crypto, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_list_available(self, async_client: AsyncBrapi) -> None: async with async_client.v2.crypto.with_streaming_response.list_available() as response: diff --git a/tests/api_resources/v2/test_currency.py b/tests/api_resources/v2/test_currency.py index 0326fc1..ee22292 100644 --- a/tests/api_resources/v2/test_currency.py +++ b/tests/api_resources/v2/test_currency.py @@ -20,41 +20,34 @@ class TestCurrency: parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve(self, client: Brapi) -> None: - currency = client.v2.currency.retrieve( - currency="USD-BRL,EUR-USD", - ) + currency = client.v2.currency.retrieve() assert_matches_type(CurrencyRetrieveResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve_with_all_params(self, client: Brapi) -> None: currency = client.v2.currency.retrieve( - currency="USD-BRL,EUR-USD", - token="token", + currency="USD-BRL", ) assert_matches_type(CurrencyRetrieveResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_retrieve(self, client: Brapi) -> None: - response = client.v2.currency.with_raw_response.retrieve( - currency="USD-BRL,EUR-USD", - ) + response = client.v2.currency.with_raw_response.retrieve() assert response.is_closed is True assert response.http_request.headers.get("X-Stainless-Lang") == "python" currency = response.parse() assert_matches_type(CurrencyRetrieveResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_retrieve(self, client: Brapi) -> None: - with client.v2.currency.with_streaming_response.retrieve( - currency="USD-BRL,EUR-USD", - ) as response: + with client.v2.currency.with_streaming_response.retrieve() as response: assert not response.is_closed assert response.http_request.headers.get("X-Stainless-Lang") == "python" @@ -63,22 +56,21 @@ def test_streaming_response_retrieve(self, client: Brapi) -> None: assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list_available(self, client: Brapi) -> None: currency = client.v2.currency.list_available() assert_matches_type(CurrencyListAvailableResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list_available_with_all_params(self, client: Brapi) -> None: currency = client.v2.currency.list_available( - token="token", - search="search", + search="USD", ) assert_matches_type(CurrencyListAvailableResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_list_available(self, client: Brapi) -> None: response = client.v2.currency.with_raw_response.list_available() @@ -88,7 +80,7 @@ def test_raw_response_list_available(self, client: Brapi) -> None: currency = response.parse() assert_matches_type(CurrencyListAvailableResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_list_available(self, client: Brapi) -> None: with client.v2.currency.with_streaming_response.list_available() as response: @@ -106,41 +98,34 @@ class TestAsyncCurrency: "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"] ) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve(self, async_client: AsyncBrapi) -> None: - currency = await async_client.v2.currency.retrieve( - currency="USD-BRL,EUR-USD", - ) + currency = await async_client.v2.currency.retrieve() assert_matches_type(CurrencyRetrieveResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve_with_all_params(self, async_client: AsyncBrapi) -> None: currency = await async_client.v2.currency.retrieve( - currency="USD-BRL,EUR-USD", - token="token", + currency="USD-BRL", ) assert_matches_type(CurrencyRetrieveResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_retrieve(self, async_client: AsyncBrapi) -> None: - response = await async_client.v2.currency.with_raw_response.retrieve( - currency="USD-BRL,EUR-USD", - ) + response = await async_client.v2.currency.with_raw_response.retrieve() assert response.is_closed is True assert response.http_request.headers.get("X-Stainless-Lang") == "python" currency = await response.parse() assert_matches_type(CurrencyRetrieveResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> None: - async with async_client.v2.currency.with_streaming_response.retrieve( - currency="USD-BRL,EUR-USD", - ) as response: + async with async_client.v2.currency.with_streaming_response.retrieve() as response: assert not response.is_closed assert response.http_request.headers.get("X-Stainless-Lang") == "python" @@ -149,22 +134,21 @@ async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> No assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list_available(self, async_client: AsyncBrapi) -> None: currency = await async_client.v2.currency.list_available() assert_matches_type(CurrencyListAvailableResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list_available_with_all_params(self, async_client: AsyncBrapi) -> None: currency = await async_client.v2.currency.list_available( - token="token", - search="search", + search="USD", ) assert_matches_type(CurrencyListAvailableResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> None: response = await async_client.v2.currency.with_raw_response.list_available() @@ -174,7 +158,7 @@ async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> No currency = await response.parse() assert_matches_type(CurrencyListAvailableResponse, currency, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_list_available(self, async_client: AsyncBrapi) -> None: async with async_client.v2.currency.with_streaming_response.list_available() as response: diff --git a/tests/api_resources/v2/test_inflation.py b/tests/api_resources/v2/test_inflation.py index 4071b4d..34b18a2 100644 --- a/tests/api_resources/v2/test_inflation.py +++ b/tests/api_resources/v2/test_inflation.py @@ -9,11 +9,7 @@ from brapi import Brapi, AsyncBrapi from tests.utils import assert_matches_type -from brapi._utils import parse_date -from brapi.types.v2 import ( - InflationRetrieveResponse, - InflationListAvailableResponse, -) +from brapi.types.v2 import InflationRetrieveResponse, InflationListAvailableResponse base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010") @@ -21,27 +17,25 @@ class TestInflation: parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve(self, client: Brapi) -> None: inflation = client.v2.inflation.retrieve() assert_matches_type(InflationRetrieveResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve_with_all_params(self, client: Brapi) -> None: inflation = client.v2.inflation.retrieve( - token="token", - country="country", - end=parse_date("2019-12-27"), - historical=True, + end="31/12/2023", + historical="false", sort_by="date", - sort_order="asc", - start=parse_date("2019-12-27"), + sort_order="desc", + start="01/01/2023", ) assert_matches_type(InflationRetrieveResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_retrieve(self, client: Brapi) -> None: response = client.v2.inflation.with_raw_response.retrieve() @@ -51,7 +45,7 @@ def test_raw_response_retrieve(self, client: Brapi) -> None: inflation = response.parse() assert_matches_type(InflationRetrieveResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_retrieve(self, client: Brapi) -> None: with client.v2.inflation.with_streaming_response.retrieve() as response: @@ -63,22 +57,13 @@ def test_streaming_response_retrieve(self, client: Brapi) -> None: assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list_available(self, client: Brapi) -> None: inflation = client.v2.inflation.list_available() assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") - @parametrize - def test_method_list_available_with_all_params(self, client: Brapi) -> None: - inflation = client.v2.inflation.list_available( - token="token", - search="search", - ) - assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) - - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_list_available(self, client: Brapi) -> None: response = client.v2.inflation.with_raw_response.list_available() @@ -88,7 +73,7 @@ def test_raw_response_list_available(self, client: Brapi) -> None: inflation = response.parse() assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_list_available(self, client: Brapi) -> None: with client.v2.inflation.with_streaming_response.list_available() as response: @@ -106,27 +91,25 @@ class TestAsyncInflation: "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"] ) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve(self, async_client: AsyncBrapi) -> None: inflation = await async_client.v2.inflation.retrieve() assert_matches_type(InflationRetrieveResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve_with_all_params(self, async_client: AsyncBrapi) -> None: inflation = await async_client.v2.inflation.retrieve( - token="token", - country="country", - end=parse_date("2019-12-27"), - historical=True, + end="31/12/2023", + historical="false", sort_by="date", - sort_order="asc", - start=parse_date("2019-12-27"), + sort_order="desc", + start="01/01/2023", ) assert_matches_type(InflationRetrieveResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_retrieve(self, async_client: AsyncBrapi) -> None: response = await async_client.v2.inflation.with_raw_response.retrieve() @@ -136,7 +119,7 @@ async def test_raw_response_retrieve(self, async_client: AsyncBrapi) -> None: inflation = await response.parse() assert_matches_type(InflationRetrieveResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> None: async with async_client.v2.inflation.with_streaming_response.retrieve() as response: @@ -148,22 +131,13 @@ async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> No assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list_available(self, async_client: AsyncBrapi) -> None: inflation = await async_client.v2.inflation.list_available() assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") - @parametrize - async def test_method_list_available_with_all_params(self, async_client: AsyncBrapi) -> None: - inflation = await async_client.v2.inflation.list_available( - token="token", - search="search", - ) - assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) - - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> None: response = await async_client.v2.inflation.with_raw_response.list_available() @@ -173,7 +147,7 @@ async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> No inflation = await response.parse() assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_list_available(self, async_client: AsyncBrapi) -> None: async with async_client.v2.inflation.with_streaming_response.list_available() as response: diff --git a/tests/api_resources/v2/test_prime_rate.py b/tests/api_resources/v2/test_prime_rate.py index ecb5738..fc3819b 100644 --- a/tests/api_resources/v2/test_prime_rate.py +++ b/tests/api_resources/v2/test_prime_rate.py @@ -9,11 +9,7 @@ from brapi import Brapi, AsyncBrapi from tests.utils import assert_matches_type -from brapi._utils import parse_date -from brapi.types.v2 import ( - PrimeRateRetrieveResponse, - PrimeRateListAvailableResponse, -) +from brapi.types.v2 import PrimeRateRetrieveResponse, PrimeRateListAvailableResponse base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010") @@ -21,27 +17,25 @@ class TestPrimeRate: parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve(self, client: Brapi) -> None: prime_rate = client.v2.prime_rate.retrieve() assert_matches_type(PrimeRateRetrieveResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_retrieve_with_all_params(self, client: Brapi) -> None: prime_rate = client.v2.prime_rate.retrieve( - token="token", - country="country", - end=parse_date("2019-12-27"), - historical=True, + end="31/12/2023", + historical="false", sort_by="date", - sort_order="asc", - start=parse_date("2019-12-27"), + sort_order="desc", + start="01/01/2023", ) assert_matches_type(PrimeRateRetrieveResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_retrieve(self, client: Brapi) -> None: response = client.v2.prime_rate.with_raw_response.retrieve() @@ -51,7 +45,7 @@ def test_raw_response_retrieve(self, client: Brapi) -> None: prime_rate = response.parse() assert_matches_type(PrimeRateRetrieveResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_retrieve(self, client: Brapi) -> None: with client.v2.prime_rate.with_streaming_response.retrieve() as response: @@ -63,22 +57,13 @@ def test_streaming_response_retrieve(self, client: Brapi) -> None: assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_method_list_available(self, client: Brapi) -> None: prime_rate = client.v2.prime_rate.list_available() assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") - @parametrize - def test_method_list_available_with_all_params(self, client: Brapi) -> None: - prime_rate = client.v2.prime_rate.list_available( - token="token", - search="search", - ) - assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) - - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_list_available(self, client: Brapi) -> None: response = client.v2.prime_rate.with_raw_response.list_available() @@ -88,7 +73,7 @@ def test_raw_response_list_available(self, client: Brapi) -> None: prime_rate = response.parse() assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_streaming_response_list_available(self, client: Brapi) -> None: with client.v2.prime_rate.with_streaming_response.list_available() as response: @@ -106,27 +91,25 @@ class TestAsyncPrimeRate: "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"] ) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve(self, async_client: AsyncBrapi) -> None: prime_rate = await async_client.v2.prime_rate.retrieve() assert_matches_type(PrimeRateRetrieveResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_retrieve_with_all_params(self, async_client: AsyncBrapi) -> None: prime_rate = await async_client.v2.prime_rate.retrieve( - token="token", - country="country", - end=parse_date("2019-12-27"), - historical=True, + end="31/12/2023", + historical="false", sort_by="date", - sort_order="asc", - start=parse_date("2019-12-27"), + sort_order="desc", + start="01/01/2023", ) assert_matches_type(PrimeRateRetrieveResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_retrieve(self, async_client: AsyncBrapi) -> None: response = await async_client.v2.prime_rate.with_raw_response.retrieve() @@ -136,7 +119,7 @@ async def test_raw_response_retrieve(self, async_client: AsyncBrapi) -> None: prime_rate = await response.parse() assert_matches_type(PrimeRateRetrieveResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> None: async with async_client.v2.prime_rate.with_streaming_response.retrieve() as response: @@ -148,22 +131,13 @@ async def test_streaming_response_retrieve(self, async_client: AsyncBrapi) -> No assert cast(Any, response.is_closed) is True - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_method_list_available(self, async_client: AsyncBrapi) -> None: prime_rate = await async_client.v2.prime_rate.list_available() assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") - @parametrize - async def test_method_list_available_with_all_params(self, async_client: AsyncBrapi) -> None: - prime_rate = await async_client.v2.prime_rate.list_available( - token="token", - search="search", - ) - assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) - - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> None: response = await async_client.v2.prime_rate.with_raw_response.list_available() @@ -173,7 +147,7 @@ async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> No prime_rate = await response.parse() assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) - @pytest.mark.skip(reason="Prism tests are disabled") + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_streaming_response_list_available(self, async_client: AsyncBrapi) -> None: async with async_client.v2.prime_rate.with_streaming_response.list_available() as response: diff --git a/tests/test_client.py b/tests/test_client.py index ad052f5..a6ba513 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -23,7 +23,7 @@ from brapi._types import Omit from brapi._utils import asyncify from brapi._models import BaseModel, FinalRequestOptions -from brapi._exceptions import BrapiError, APIStatusError, APITimeoutError, APIResponseValidationError +from brapi._exceptions import APIStatusError, APITimeoutError, APIResponseValidationError from brapi._base_client import ( DEFAULT_TIMEOUT, HTTPX_DEFAULT_TIMEOUT, @@ -397,16 +397,6 @@ def test_default_headers_option(self) -> None: test_client.close() test_client2.close() - def test_validate_headers(self) -> None: - client = Brapi(base_url=base_url, api_key=api_key, _strict_response_validation=True) - request = client._build_request(FinalRequestOptions(method="get", url="/foo")) - assert request.headers.get("Authorization") == f"Bearer {api_key}" - - with pytest.raises(BrapiError): - with update_env(**{"BRAPI_API_KEY": Omit()}): - client2 = Brapi(base_url=base_url, api_key=None, _strict_response_validation=True) - _ = client2 - def test_default_query_option(self) -> None: client = Brapi( base_url=base_url, api_key=api_key, _strict_response_validation=True, default_query={"query_param": "bar"} @@ -427,6 +417,30 @@ def test_default_query_option(self) -> None: client.close() + def test_hardcoded_query_params_in_url(self, client: Brapi) -> None: + request = client._build_request(FinalRequestOptions(method="get", url="/foo?beta=true")) + url = httpx.URL(request.url) + assert dict(url.params) == {"beta": "true"} + + request = client._build_request( + FinalRequestOptions( + method="get", + url="/foo?beta=true", + params={"limit": "10", "page": "abc"}, + ) + ) + url = httpx.URL(request.url) + assert dict(url.params) == {"beta": "true", "limit": "10", "page": "abc"} + + request = client._build_request( + FinalRequestOptions( + method="get", + url="/files/a%2Fb?beta=true", + params={"limit": "10"}, + ) + ) + assert request.url.raw_path == b"/files/a%2Fb?beta=true&limit=10" + def test_request_extra_json(self, client: Brapi) -> None: request = client._build_request( FinalRequestOptions( @@ -859,20 +873,20 @@ def test_parse_retry_after_header( @mock.patch("brapi._base_client.BaseClient._calculate_retry_timeout", _low_retry_timeout) @pytest.mark.respx(base_url=base_url) def test_retrying_timeout_errors_doesnt_leak(self, respx_mock: MockRouter, client: Brapi) -> None: - respx_mock.get("/api/quote/PETR4,MGLU3").mock(side_effect=httpx.TimeoutException("Test timeout error")) + respx_mock.get("/api/quote/PETR4,VALE3").mock(side_effect=httpx.TimeoutException("Test timeout error")) with pytest.raises(APITimeoutError): - client.quote.with_streaming_response.retrieve(tickers="PETR4,MGLU3").__enter__() + client.quote.with_streaming_response.retrieve(tickers="PETR4,VALE3").__enter__() assert _get_open_connections(client) == 0 @mock.patch("brapi._base_client.BaseClient._calculate_retry_timeout", _low_retry_timeout) @pytest.mark.respx(base_url=base_url) def test_retrying_status_errors_doesnt_leak(self, respx_mock: MockRouter, client: Brapi) -> None: - respx_mock.get("/api/quote/PETR4,MGLU3").mock(return_value=httpx.Response(500)) + respx_mock.get("/api/quote/PETR4,VALE3").mock(return_value=httpx.Response(500)) with pytest.raises(APIStatusError): - client.quote.with_streaming_response.retrieve(tickers="PETR4,MGLU3").__enter__() + client.quote.with_streaming_response.retrieve(tickers="PETR4,VALE3").__enter__() assert _get_open_connections(client) == 0 @pytest.mark.parametrize("failures_before_success", [0, 2, 4]) @@ -899,9 +913,9 @@ def retry_handler(_request: httpx.Request) -> httpx.Response: return httpx.Response(500) return httpx.Response(200) - respx_mock.get("/api/quote/PETR4,MGLU3").mock(side_effect=retry_handler) + respx_mock.get("/api/quote/PETR4,VALE3").mock(side_effect=retry_handler) - response = client.quote.with_raw_response.retrieve(tickers="PETR4,MGLU3") + response = client.quote.with_raw_response.retrieve(tickers="PETR4,VALE3") assert response.retries_taken == failures_before_success assert int(response.http_request.headers.get("x-stainless-retry-count")) == failures_before_success @@ -921,10 +935,10 @@ def retry_handler(_request: httpx.Request) -> httpx.Response: return httpx.Response(500) return httpx.Response(200) - respx_mock.get("/api/quote/PETR4,MGLU3").mock(side_effect=retry_handler) + respx_mock.get("/api/quote/PETR4,VALE3").mock(side_effect=retry_handler) response = client.quote.with_raw_response.retrieve( - tickers="PETR4,MGLU3", extra_headers={"x-stainless-retry-count": Omit()} + tickers="PETR4,VALE3", extra_headers={"x-stainless-retry-count": Omit()} ) assert len(response.http_request.headers.get_list("x-stainless-retry-count")) == 0 @@ -946,10 +960,10 @@ def retry_handler(_request: httpx.Request) -> httpx.Response: return httpx.Response(500) return httpx.Response(200) - respx_mock.get("/api/quote/PETR4,MGLU3").mock(side_effect=retry_handler) + respx_mock.get("/api/quote/PETR4,VALE3").mock(side_effect=retry_handler) response = client.quote.with_raw_response.retrieve( - tickers="PETR4,MGLU3", extra_headers={"x-stainless-retry-count": "42"} + tickers="PETR4,VALE3", extra_headers={"x-stainless-retry-count": "42"} ) assert response.http_request.headers.get("x-stainless-retry-count") == "42" @@ -957,6 +971,14 @@ def retry_handler(_request: httpx.Request) -> httpx.Response: def test_proxy_environment_variables(self, monkeypatch: pytest.MonkeyPatch) -> None: # Test that the proxy environment variables are set correctly monkeypatch.setenv("HTTPS_PROXY", "https://example.org") + # Delete in case our environment has any proxy env vars set + monkeypatch.delenv("HTTP_PROXY", raising=False) + monkeypatch.delenv("ALL_PROXY", raising=False) + monkeypatch.delenv("NO_PROXY", raising=False) + monkeypatch.delenv("http_proxy", raising=False) + monkeypatch.delenv("https_proxy", raising=False) + monkeypatch.delenv("all_proxy", raising=False) + monkeypatch.delenv("no_proxy", raising=False) client = DefaultHttpxClient() @@ -1292,16 +1314,6 @@ async def test_default_headers_option(self) -> None: await test_client.close() await test_client2.close() - def test_validate_headers(self) -> None: - client = AsyncBrapi(base_url=base_url, api_key=api_key, _strict_response_validation=True) - request = client._build_request(FinalRequestOptions(method="get", url="/foo")) - assert request.headers.get("Authorization") == f"Bearer {api_key}" - - with pytest.raises(BrapiError): - with update_env(**{"BRAPI_API_KEY": Omit()}): - client2 = AsyncBrapi(base_url=base_url, api_key=None, _strict_response_validation=True) - _ = client2 - async def test_default_query_option(self) -> None: client = AsyncBrapi( base_url=base_url, api_key=api_key, _strict_response_validation=True, default_query={"query_param": "bar"} @@ -1322,6 +1334,30 @@ async def test_default_query_option(self) -> None: await client.close() + async def test_hardcoded_query_params_in_url(self, async_client: AsyncBrapi) -> None: + request = async_client._build_request(FinalRequestOptions(method="get", url="/foo?beta=true")) + url = httpx.URL(request.url) + assert dict(url.params) == {"beta": "true"} + + request = async_client._build_request( + FinalRequestOptions( + method="get", + url="/foo?beta=true", + params={"limit": "10", "page": "abc"}, + ) + ) + url = httpx.URL(request.url) + assert dict(url.params) == {"beta": "true", "limit": "10", "page": "abc"} + + request = async_client._build_request( + FinalRequestOptions( + method="get", + url="/files/a%2Fb?beta=true", + params={"limit": "10"}, + ) + ) + assert request.url.raw_path == b"/files/a%2Fb?beta=true&limit=10" + def test_request_extra_json(self, client: Brapi) -> None: request = client._build_request( FinalRequestOptions( @@ -1769,20 +1805,20 @@ async def test_parse_retry_after_header( @mock.patch("brapi._base_client.BaseClient._calculate_retry_timeout", _low_retry_timeout) @pytest.mark.respx(base_url=base_url) async def test_retrying_timeout_errors_doesnt_leak(self, respx_mock: MockRouter, async_client: AsyncBrapi) -> None: - respx_mock.get("/api/quote/PETR4,MGLU3").mock(side_effect=httpx.TimeoutException("Test timeout error")) + respx_mock.get("/api/quote/PETR4,VALE3").mock(side_effect=httpx.TimeoutException("Test timeout error")) with pytest.raises(APITimeoutError): - await async_client.quote.with_streaming_response.retrieve(tickers="PETR4,MGLU3").__aenter__() + await async_client.quote.with_streaming_response.retrieve(tickers="PETR4,VALE3").__aenter__() assert _get_open_connections(async_client) == 0 @mock.patch("brapi._base_client.BaseClient._calculate_retry_timeout", _low_retry_timeout) @pytest.mark.respx(base_url=base_url) async def test_retrying_status_errors_doesnt_leak(self, respx_mock: MockRouter, async_client: AsyncBrapi) -> None: - respx_mock.get("/api/quote/PETR4,MGLU3").mock(return_value=httpx.Response(500)) + respx_mock.get("/api/quote/PETR4,VALE3").mock(return_value=httpx.Response(500)) with pytest.raises(APIStatusError): - await async_client.quote.with_streaming_response.retrieve(tickers="PETR4,MGLU3").__aenter__() + await async_client.quote.with_streaming_response.retrieve(tickers="PETR4,VALE3").__aenter__() assert _get_open_connections(async_client) == 0 @pytest.mark.parametrize("failures_before_success", [0, 2, 4]) @@ -1809,9 +1845,9 @@ def retry_handler(_request: httpx.Request) -> httpx.Response: return httpx.Response(500) return httpx.Response(200) - respx_mock.get("/api/quote/PETR4,MGLU3").mock(side_effect=retry_handler) + respx_mock.get("/api/quote/PETR4,VALE3").mock(side_effect=retry_handler) - response = await client.quote.with_raw_response.retrieve(tickers="PETR4,MGLU3") + response = await client.quote.with_raw_response.retrieve(tickers="PETR4,VALE3") assert response.retries_taken == failures_before_success assert int(response.http_request.headers.get("x-stainless-retry-count")) == failures_before_success @@ -1833,10 +1869,10 @@ def retry_handler(_request: httpx.Request) -> httpx.Response: return httpx.Response(500) return httpx.Response(200) - respx_mock.get("/api/quote/PETR4,MGLU3").mock(side_effect=retry_handler) + respx_mock.get("/api/quote/PETR4,VALE3").mock(side_effect=retry_handler) response = await client.quote.with_raw_response.retrieve( - tickers="PETR4,MGLU3", extra_headers={"x-stainless-retry-count": Omit()} + tickers="PETR4,VALE3", extra_headers={"x-stainless-retry-count": Omit()} ) assert len(response.http_request.headers.get_list("x-stainless-retry-count")) == 0 @@ -1858,10 +1894,10 @@ def retry_handler(_request: httpx.Request) -> httpx.Response: return httpx.Response(500) return httpx.Response(200) - respx_mock.get("/api/quote/PETR4,MGLU3").mock(side_effect=retry_handler) + respx_mock.get("/api/quote/PETR4,VALE3").mock(side_effect=retry_handler) response = await client.quote.with_raw_response.retrieve( - tickers="PETR4,MGLU3", extra_headers={"x-stainless-retry-count": "42"} + tickers="PETR4,VALE3", extra_headers={"x-stainless-retry-count": "42"} ) assert response.http_request.headers.get("x-stainless-retry-count") == "42" @@ -1873,6 +1909,14 @@ async def test_get_platform(self) -> None: async def test_proxy_environment_variables(self, monkeypatch: pytest.MonkeyPatch) -> None: # Test that the proxy environment variables are set correctly monkeypatch.setenv("HTTPS_PROXY", "https://example.org") + # Delete in case our environment has any proxy env vars set + monkeypatch.delenv("HTTP_PROXY", raising=False) + monkeypatch.delenv("ALL_PROXY", raising=False) + monkeypatch.delenv("NO_PROXY", raising=False) + monkeypatch.delenv("http_proxy", raising=False) + monkeypatch.delenv("https_proxy", raising=False) + monkeypatch.delenv("all_proxy", raising=False) + monkeypatch.delenv("no_proxy", raising=False) client = DefaultAsyncHttpxClient() diff --git a/tests/test_deepcopy.py b/tests/test_deepcopy.py deleted file mode 100644 index f5639fb..0000000 --- a/tests/test_deepcopy.py +++ /dev/null @@ -1,58 +0,0 @@ -from brapi._utils import deepcopy_minimal - - -def assert_different_identities(obj1: object, obj2: object) -> None: - assert obj1 == obj2 - assert id(obj1) != id(obj2) - - -def test_simple_dict() -> None: - obj1 = {"foo": "bar"} - obj2 = deepcopy_minimal(obj1) - assert_different_identities(obj1, obj2) - - -def test_nested_dict() -> None: - obj1 = {"foo": {"bar": True}} - obj2 = deepcopy_minimal(obj1) - assert_different_identities(obj1, obj2) - assert_different_identities(obj1["foo"], obj2["foo"]) - - -def test_complex_nested_dict() -> None: - obj1 = {"foo": {"bar": [{"hello": "world"}]}} - obj2 = deepcopy_minimal(obj1) - assert_different_identities(obj1, obj2) - assert_different_identities(obj1["foo"], obj2["foo"]) - assert_different_identities(obj1["foo"]["bar"], obj2["foo"]["bar"]) - assert_different_identities(obj1["foo"]["bar"][0], obj2["foo"]["bar"][0]) - - -def test_simple_list() -> None: - obj1 = ["a", "b", "c"] - obj2 = deepcopy_minimal(obj1) - assert_different_identities(obj1, obj2) - - -def test_nested_list() -> None: - obj1 = ["a", [1, 2, 3]] - obj2 = deepcopy_minimal(obj1) - assert_different_identities(obj1, obj2) - assert_different_identities(obj1[1], obj2[1]) - - -class MyObject: ... - - -def test_ignores_other_types() -> None: - # custom classes - my_obj = MyObject() - obj1 = {"foo": my_obj} - obj2 = deepcopy_minimal(obj1) - assert_different_identities(obj1, obj2) - assert obj1["foo"] is my_obj - - # tuples - obj3 = ("a", "b") - obj4 = deepcopy_minimal(obj3) - assert obj3 is obj4 diff --git a/tests/test_extract_files.py b/tests/test_extract_files.py index 9b6f362..eb0cc9e 100644 --- a/tests/test_extract_files.py +++ b/tests/test_extract_files.py @@ -4,7 +4,7 @@ import pytest -from brapi._types import FileTypes +from brapi._types import FileTypes, ArrayFormat from brapi._utils import extract_files @@ -35,6 +35,12 @@ def test_multiple_files() -> None: assert query == {"documents": [{}, {}]} +def test_top_level_file_array() -> None: + query = {"files": [b"file one", b"file two"], "title": "hello"} + assert extract_files(query, paths=[["files", ""]]) == [("files[]", b"file one"), ("files[]", b"file two")] + assert query == {"title": "hello"} + + @pytest.mark.parametrize( "query,paths,expected", [ @@ -62,3 +68,24 @@ def test_ignores_incorrect_paths( expected: list[tuple[str, FileTypes]], ) -> None: assert extract_files(query, paths=paths) == expected + + +@pytest.mark.parametrize( + "array_format,expected_top_level,expected_nested", + [ + ("brackets", [("files[]", b"a"), ("files[]", b"b")], [("items[][file]", b"a"), ("items[][file]", b"b")]), + ("repeat", [("files", b"a"), ("files", b"b")], [("items[file]", b"a"), ("items[file]", b"b")]), + ("comma", [("files", b"a"), ("files", b"b")], [("items[file]", b"a"), ("items[file]", b"b")]), + ("indices", [("files[0]", b"a"), ("files[1]", b"b")], [("items[0][file]", b"a"), ("items[1][file]", b"b")]), + ], +) +def test_array_format_controls_file_field_names( + array_format: ArrayFormat, + expected_top_level: list[tuple[str, FileTypes]], + expected_nested: list[tuple[str, FileTypes]], +) -> None: + top_level = {"files": [b"a", b"b"]} + assert extract_files(top_level, paths=[["files", ""]], array_format=array_format) == expected_top_level + + nested = {"items": [{"file": b"a"}, {"file": b"b"}]} + assert extract_files(nested, paths=[["items", "", "file"]], array_format=array_format) == expected_nested diff --git a/tests/test_files.py b/tests/test_files.py index bdb3673..1169fc3 100644 --- a/tests/test_files.py +++ b/tests/test_files.py @@ -4,7 +4,8 @@ import pytest from dirty_equals import IsDict, IsList, IsBytes, IsTuple -from brapi._files import to_httpx_files, async_to_httpx_files +from brapi._files import to_httpx_files, deepcopy_with_paths, async_to_httpx_files +from brapi._utils import extract_files readme_path = Path(__file__).parent.parent.joinpath("README.md") @@ -49,3 +50,99 @@ def test_string_not_allowed() -> None: "file": "foo", # type: ignore } ) + + +def assert_different_identities(obj1: object, obj2: object) -> None: + assert obj1 == obj2 + assert obj1 is not obj2 + + +class TestDeepcopyWithPaths: + def test_copies_top_level_dict(self) -> None: + original = {"file": b"data", "other": "value"} + result = deepcopy_with_paths(original, [["file"]]) + assert_different_identities(result, original) + + def test_file_value_is_same_reference(self) -> None: + file_bytes = b"contents" + original = {"file": file_bytes} + result = deepcopy_with_paths(original, [["file"]]) + assert_different_identities(result, original) + assert result["file"] is file_bytes + + def test_list_popped_wholesale(self) -> None: + files = [b"f1", b"f2"] + original = {"files": files, "title": "t"} + result = deepcopy_with_paths(original, [["files", ""]]) + assert_different_identities(result, original) + result_files = result["files"] + assert isinstance(result_files, list) + assert_different_identities(result_files, files) + + def test_nested_array_path_copies_list_and_elements(self) -> None: + elem1 = {"file": b"f1", "extra": 1} + elem2 = {"file": b"f2", "extra": 2} + original = {"items": [elem1, elem2]} + result = deepcopy_with_paths(original, [["items", "", "file"]]) + assert_different_identities(result, original) + result_items = result["items"] + assert isinstance(result_items, list) + assert_different_identities(result_items, original["items"]) + assert_different_identities(result_items[0], elem1) + assert_different_identities(result_items[1], elem2) + + def test_empty_paths_returns_same_object(self) -> None: + original = {"foo": "bar"} + result = deepcopy_with_paths(original, []) + assert result is original + + def test_multiple_paths(self) -> None: + f1 = b"file1" + f2 = b"file2" + original = {"a": f1, "b": f2, "c": "unchanged"} + result = deepcopy_with_paths(original, [["a"], ["b"]]) + assert_different_identities(result, original) + assert result["a"] is f1 + assert result["b"] is f2 + assert result["c"] is original["c"] + + def test_extract_files_does_not_mutate_original_top_level(self) -> None: + file_bytes = b"contents" + original = {"file": file_bytes, "other": "value"} + + copied = deepcopy_with_paths(original, [["file"]]) + extracted = extract_files(copied, paths=[["file"]]) + + assert extracted == [("file", file_bytes)] + assert original == {"file": file_bytes, "other": "value"} + assert copied == {"other": "value"} + + def test_extract_files_does_not_mutate_original_nested_array_path(self) -> None: + file1 = b"f1" + file2 = b"f2" + original = { + "items": [ + {"file": file1, "extra": 1}, + {"file": file2, "extra": 2}, + ], + "title": "example", + } + + copied = deepcopy_with_paths(original, [["items", "", "file"]]) + extracted = extract_files(copied, paths=[["items", "", "file"]]) + + assert [entry for _, entry in extracted] == [file1, file2] + assert original == { + "items": [ + {"file": file1, "extra": 1}, + {"file": file2, "extra": 2}, + ], + "title": "example", + } + assert copied == { + "items": [ + {"extra": 1}, + {"extra": 2}, + ], + "title": "example", + } diff --git a/tests/test_utils/test_path.py b/tests/test_utils/test_path.py new file mode 100644 index 0000000..a179117 --- /dev/null +++ b/tests/test_utils/test_path.py @@ -0,0 +1,89 @@ +from __future__ import annotations + +from typing import Any + +import pytest + +from brapi._utils._path import path_template + + +@pytest.mark.parametrize( + "template, kwargs, expected", + [ + ("/v1/{id}", dict(id="abc"), "/v1/abc"), + ("/v1/{a}/{b}", dict(a="x", b="y"), "/v1/x/y"), + ("/v1/{a}{b}/path/{c}?val={d}#{e}", dict(a="x", b="y", c="z", d="u", e="v"), "/v1/xy/path/z?val=u#v"), + ("/{w}/{w}", dict(w="echo"), "/echo/echo"), + ("/v1/static", {}, "/v1/static"), + ("", {}, ""), + ("/v1/?q={n}&count=10", dict(n=42), "/v1/?q=42&count=10"), + ("/v1/{v}", dict(v=None), "/v1/null"), + ("/v1/{v}", dict(v=True), "/v1/true"), + ("/v1/{v}", dict(v=False), "/v1/false"), + ("/v1/{v}", dict(v=".hidden"), "/v1/.hidden"), # dot prefix ok + ("/v1/{v}", dict(v="file.txt"), "/v1/file.txt"), # dot in middle ok + ("/v1/{v}", dict(v="..."), "/v1/..."), # triple dot ok + ("/v1/{a}{b}", dict(a=".", b="txt"), "/v1/.txt"), # dot var combining with adjacent to be ok + ("/items?q={v}#{f}", dict(v=".", f=".."), "/items?q=.#.."), # dots in query/fragment are fine + ( + "/v1/{a}?query={b}", + dict(a="../../other/endpoint", b="a&bad=true"), + "/v1/..%2F..%2Fother%2Fendpoint?query=a%26bad%3Dtrue", + ), + ("/v1/{val}", dict(val="a/b/c"), "/v1/a%2Fb%2Fc"), + ("/v1/{val}", dict(val="a/b/c?query=value"), "/v1/a%2Fb%2Fc%3Fquery=value"), + ("/v1/{val}", dict(val="a/b/c?query=value&bad=true"), "/v1/a%2Fb%2Fc%3Fquery=value&bad=true"), + ("/v1/{val}", dict(val="%20"), "/v1/%2520"), # escapes escape sequences in input + # Query: slash and ? are safe, # is not + ("/items?q={v}", dict(v="a/b"), "/items?q=a/b"), + ("/items?q={v}", dict(v="a?b"), "/items?q=a?b"), + ("/items?q={v}", dict(v="a#b"), "/items?q=a%23b"), + ("/items?q={v}", dict(v="a b"), "/items?q=a%20b"), + # Fragment: slash and ? are safe + ("/docs#{v}", dict(v="a/b"), "/docs#a/b"), + ("/docs#{v}", dict(v="a?b"), "/docs#a?b"), + # Path: slash, ? and # are all encoded + ("/v1/{v}", dict(v="a/b"), "/v1/a%2Fb"), + ("/v1/{v}", dict(v="a?b"), "/v1/a%3Fb"), + ("/v1/{v}", dict(v="a#b"), "/v1/a%23b"), + # same var encoded differently by component + ( + "/v1/{v}?q={v}#{v}", + dict(v="a/b?c#d"), + "/v1/a%2Fb%3Fc%23d?q=a/b?c%23d#a/b?c%23d", + ), + ("/v1/{val}", dict(val="x?admin=true"), "/v1/x%3Fadmin=true"), # query injection + ("/v1/{val}", dict(val="x#admin"), "/v1/x%23admin"), # fragment injection + ], +) +def test_interpolation(template: str, kwargs: dict[str, Any], expected: str) -> None: + assert path_template(template, **kwargs) == expected + + +def test_missing_kwarg_raises_key_error() -> None: + with pytest.raises(KeyError, match="org_id"): + path_template("/v1/{org_id}") + + +@pytest.mark.parametrize( + "template, kwargs", + [ + ("{a}/path", dict(a=".")), + ("{a}/path", dict(a="..")), + ("/v1/{a}", dict(a=".")), + ("/v1/{a}", dict(a="..")), + ("/v1/{a}/path", dict(a=".")), + ("/v1/{a}/path", dict(a="..")), + ("/v1/{a}{b}", dict(a=".", b=".")), # adjacent vars → ".." + ("/v1/{a}.", dict(a=".")), # var + static → ".." + ("/v1/{a}{b}", dict(a="", b=".")), # empty + dot → "." + ("/v1/%2e/{x}", dict(x="ok")), # encoded dot in static text + ("/v1/%2e./{x}", dict(x="ok")), # mixed encoded ".." in static + ("/v1/.%2E/{x}", dict(x="ok")), # mixed encoded ".." in static + ("/v1/{v}?q=1", dict(v="..")), + ("/v1/{v}#frag", dict(v="..")), + ], +) +def test_dot_segment_rejected(template: str, kwargs: dict[str, Any]) -> None: + with pytest.raises(ValueError, match="dot-segment"): + path_template(template, **kwargs)