parseapi 1.3.0__tar.gz → 1.6.0__tar.gz

{parseapi-1.3.0 → parseapi-1.6.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.6.0 - 2026-09-24
+
+Adds Time location inputs and explicit ambiguity candidates, filtered timezone discovery, multiple conversion targets, wall-time disambiguation, and standard/seasonal offset detail. Existing Timezone methods and API 2.0.0 selection remain unchanged.
+
+## 1.4.0 - 2026-09-24
+
+Adds Australian Postal suburb choices while preserving null, empty, and ambiguous results. Existing calls, compact nearby/distance responses, and API contract `2.0.0` remain unchanged.
+
 ## 1.3.0 - Unreleased
 
 Adds Stack site inventory lookup with eight technology category arrays, nullable versions, and explicit page coverage. Stack uses a 35-second default attempt timeout while explicit caller settings remain honored. Existing calls and API contract `2.0.0` remain unchanged.

{parseapi-1.3.0 → parseapi-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: parseapi
-Version: 1.3.0
+Version: 1.6.0
 Summary: Official ParseAPI client for Python. One key, minimal JSON, fast.
 Project-URL: Homepage, https://parseapi.com
 Project-URL: Documentation, https://parseapi.com/docs
@@ -36,7 +36,7 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Version 1.3.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
+Version 1.6.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
 
 Upgrade the dependency in staging, review the [release notes](https://parseapi.com/docs/releases), and test the application before deploying the same code and dependency version to production. Commit your dependency lockfile so the tested package travels with your deployment. Future major SDK upgrades can select a newer API contract.
 
@@ -170,7 +170,49 @@ The next call keeps its usual default unless it also supplies `lang`. Existing `
 
 ## Time
 
-`time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `deep.offset_seconds` gives the numeric offset, while `deep.offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to`, an offsetless `at` is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing `timezone` methods remain supported.
+`time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `deep.offset_seconds` gives the numeric offset, while `deep.offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to` or `targets`, an offsetless `at` is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing `timezone` methods remain supported.
+
+For an offsetless `at` with `to` or `targets`, choose how to handle a clock change with `disambiguation`. It applies to named-zone and coordinate Time calls.
+
+| Value | Repeated time | Skipped time |
+| --- | --- | --- |
+| `compatible` (default) | Earlier occurrence | Shift forward by the clock change |
+| `earlier` | Earlier occurrence | Shift backward by the clock change |
+| `later` | Later occurrence | Shift forward by the clock change |
+| `reject` | `400 ambiguous_time` | `400 nonexistent_time` |
+
+An explicit UTC offset selects an instant directly. For example, `2026-11-01T01:30:00-04:00` and `2026-11-01T01:30:00-05:00` identify the two New York occurrences. A valid `disambiguation` value has no effect on explicit instants, current-time requests or lookups without `to` or `targets`. For user-entered appointment times, start with `reject`. Handle `ambiguous_time` or `nonexistent_time` by collecting an explicit offset or an earlier/later choice from the user. Other malformed input still uses `invalid_request`.
+
+```python
+result = parse.time("America/New_York", at="2026-11-01T01:30:00",
+                    to="UTC", disambiguation="later")
+print(result["to"]["at"])  # 2026-11-01T06:30:00+00:00
+```
+
+Canonical Time `deep` includes the pinned rule edition in `deep.timezone_database_version` and source-wall resolution in `deep.resolution`. Resolution records `kind` (`unique`, `overlap` or `gap`), the selected policy, signed `adjustment_seconds`, and chronological alternatives with exact `at`, Unix seconds and UTC offset. Unique times have an empty alternatives list. Explicit instants, current time and lookups without conversion have null resolution. Destination detail stays compact.
+
+Search serving IANA IDs by city or region, or omit the query to list all (Go and Rust use an empty string). Discovery returns `timezone_database_version` and sorted `timezones`. No search matches returns `timezones: []`.
+
+Pass `targets` to convert one instant to 1-10 zones in a single pooled request. The native list preserves order and duplicates. Use `targets` instead of `to`. The response adds `targets`, with optional detail inside each target. Unknown source coordinates return `targets: null`. An unknown destination rejects the whole request with `not_found`. Omission keeps the original response shape.
+
+```python
+zones = parse.time.zones('New York')
+result = parse.time('UTC', at='2026-09-24T12:00:00Z',
+                    targets=['America/New_York', 'Asia/Tokyo'])
+print(zones['timezones'], result['targets'])
+```
+
+### Location inputs and timezone filters
+
+`parse.time(iata="JFK", deep=True)` and `parse.time.zones(country="US", dst=False, observes_dst=True, details=True)`.
+
+Choose one explicit location input: IP, exact city name or stable city ID, country, IATA airport, ICAO airport, port UN/LOCODE, or address. Country and state can narrow a city or address. State requires country. Address lookup requires US country context and a strict address-point match. Port lookup covers the reviewed port subset, not every assigned UN/LOCODE. IP lookup always uses the supplied IP.
+
+Location calls add `location` with `status`, `candidates`, `truncated`, `source` and the typed input. Check `status` before using the clock: ambiguous or missing locations retain null time fields. Candidate coordinates and IDs can also be null. A country with multiple timezones does not silently choose one. Named-zone and coordinate calls retain their existing signatures.
+
+Timezone discovery accepts country, IANA area, exact signed offset, abbreviation, DST-at-instant and observes-DST-during-year filters. `at` selects the common instant, `sort` selects timezone or offset order, and `details` adds `zones` rows plus the evaluation `at`. The default `timezones` list stays compact. False DST filters are sent explicitly. An abbreviation returns candidate zones rather than choosing one. Observes-DST uses the UTC calendar year containing `at`.
+
+Source deep adds `standard_offset`, `standard_offset_seconds`, signed `dst_offset_seconds` and `season`. Seasonal adjustments can be negative. `season` describes the current DST-flag interval, or the next within 400 days, with actual before/after transition facts and signed `change_seconds`. Unknown boundaries remain null. These fields are optional and nullable, and destination deep stays compact.
 
 ## Measurements
 
@@ -185,6 +227,8 @@ Unit discovery accepts optional `query`, `type`, and `unit` filters. `unit` sele
 
 ## Place statistics and optional detail
 
+Australian postal lookups include core `localities` with suburb choices (`city`, `state`, `state_name`) on every plan. Null or an omitted field means unknown, while `[]` means the reviewed reference has no eligible choices. `city` stays null when the source is ambiguous, even if there is only one eligible choice. Let the user select their suburb and keep manual entry available. These are geographic choices, not mailing-address verification. [G-NAF source, adaptations and licence](https://parseapi.com/legal/attribution#postal-au).
+
 Postal and District paid profiles include `deep.property_tax` where supported. It contains `annual_median`, `currency` and `period`: median annual property tax payable on owner-occupied homes in the statistical area. The amount is adjusted to the final year of the reporting period (`YYYY-YYYY`). This is an area statistic, not a rate or an individual property bill. Unsupported, missing and censored estimates are null.
 
 ```python

{parseapi-1.3.0 → parseapi-1.6.0}/README.md

@@ -17,7 +17,7 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Version 1.3.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
+Version 1.6.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
 
 Upgrade the dependency in staging, review the [release notes](https://parseapi.com/docs/releases), and test the application before deploying the same code and dependency version to production. Commit your dependency lockfile so the tested package travels with your deployment. Future major SDK upgrades can select a newer API contract.
 
@@ -151,7 +151,49 @@ The next call keeps its usual default unless it also supplies `lang`. Existing `
 
 ## Time
 
-`time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `deep.offset_seconds` gives the numeric offset, while `deep.offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to`, an offsetless `at` is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing `timezone` methods remain supported.
+`time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `deep.offset_seconds` gives the numeric offset, while `deep.offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to` or `targets`, an offsetless `at` is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing `timezone` methods remain supported.
+
+For an offsetless `at` with `to` or `targets`, choose how to handle a clock change with `disambiguation`. It applies to named-zone and coordinate Time calls.
+
+| Value | Repeated time | Skipped time |
+| --- | --- | --- |
+| `compatible` (default) | Earlier occurrence | Shift forward by the clock change |
+| `earlier` | Earlier occurrence | Shift backward by the clock change |
+| `later` | Later occurrence | Shift forward by the clock change |
+| `reject` | `400 ambiguous_time` | `400 nonexistent_time` |
+
+An explicit UTC offset selects an instant directly. For example, `2026-11-01T01:30:00-04:00` and `2026-11-01T01:30:00-05:00` identify the two New York occurrences. A valid `disambiguation` value has no effect on explicit instants, current-time requests or lookups without `to` or `targets`. For user-entered appointment times, start with `reject`. Handle `ambiguous_time` or `nonexistent_time` by collecting an explicit offset or an earlier/later choice from the user. Other malformed input still uses `invalid_request`.
+
+```python
+result = parse.time("America/New_York", at="2026-11-01T01:30:00",
+                    to="UTC", disambiguation="later")
+print(result["to"]["at"])  # 2026-11-01T06:30:00+00:00
+```
+
+Canonical Time `deep` includes the pinned rule edition in `deep.timezone_database_version` and source-wall resolution in `deep.resolution`. Resolution records `kind` (`unique`, `overlap` or `gap`), the selected policy, signed `adjustment_seconds`, and chronological alternatives with exact `at`, Unix seconds and UTC offset. Unique times have an empty alternatives list. Explicit instants, current time and lookups without conversion have null resolution. Destination detail stays compact.
+
+Search serving IANA IDs by city or region, or omit the query to list all (Go and Rust use an empty string). Discovery returns `timezone_database_version` and sorted `timezones`. No search matches returns `timezones: []`.
+
+Pass `targets` to convert one instant to 1-10 zones in a single pooled request. The native list preserves order and duplicates. Use `targets` instead of `to`. The response adds `targets`, with optional detail inside each target. Unknown source coordinates return `targets: null`. An unknown destination rejects the whole request with `not_found`. Omission keeps the original response shape.
+
+```python
+zones = parse.time.zones('New York')
+result = parse.time('UTC', at='2026-09-24T12:00:00Z',
+                    targets=['America/New_York', 'Asia/Tokyo'])
+print(zones['timezones'], result['targets'])
+```
+
+### Location inputs and timezone filters
+
+`parse.time(iata="JFK", deep=True)` and `parse.time.zones(country="US", dst=False, observes_dst=True, details=True)`.
+
+Choose one explicit location input: IP, exact city name or stable city ID, country, IATA airport, ICAO airport, port UN/LOCODE, or address. Country and state can narrow a city or address. State requires country. Address lookup requires US country context and a strict address-point match. Port lookup covers the reviewed port subset, not every assigned UN/LOCODE. IP lookup always uses the supplied IP.
+
+Location calls add `location` with `status`, `candidates`, `truncated`, `source` and the typed input. Check `status` before using the clock: ambiguous or missing locations retain null time fields. Candidate coordinates and IDs can also be null. A country with multiple timezones does not silently choose one. Named-zone and coordinate calls retain their existing signatures.
+
+Timezone discovery accepts country, IANA area, exact signed offset, abbreviation, DST-at-instant and observes-DST-during-year filters. `at` selects the common instant, `sort` selects timezone or offset order, and `details` adds `zones` rows plus the evaluation `at`. The default `timezones` list stays compact. False DST filters are sent explicitly. An abbreviation returns candidate zones rather than choosing one. Observes-DST uses the UTC calendar year containing `at`.
+
+Source deep adds `standard_offset`, `standard_offset_seconds`, signed `dst_offset_seconds` and `season`. Seasonal adjustments can be negative. `season` describes the current DST-flag interval, or the next within 400 days, with actual before/after transition facts and signed `change_seconds`. Unknown boundaries remain null. These fields are optional and nullable, and destination deep stays compact.
 
 ## Measurements
 
@@ -166,6 +208,8 @@ Unit discovery accepts optional `query`, `type`, and `unit` filters. `unit` sele
 
 ## Place statistics and optional detail
 
+Australian postal lookups include core `localities` with suburb choices (`city`, `state`, `state_name`) on every plan. Null or an omitted field means unknown, while `[]` means the reviewed reference has no eligible choices. `city` stays null when the source is ambiguous, even if there is only one eligible choice. Let the user select their suburb and keep manual entry available. These are geographic choices, not mailing-address verification. [G-NAF source, adaptations and licence](https://parseapi.com/legal/attribution#postal-au).
+
 Postal and District paid profiles include `deep.property_tax` where supported. It contains `annual_median`, `currency` and `period`: median annual property tax payable on owner-occupied homes in the statistical area. The amount is adjusted to the final year of the reporting period (`YYYY-YYYY`). This is an area statistic, not a rate or an individual property bill. Unsupported, missing and censored estimates are null.
 
 ```python

{parseapi-1.3.0 → parseapi-1.6.0}/api/public.json

@@ -1371,6 +1371,66 @@
           "kind": "KEYWORD_ONLY",
           "name": "lang",
           "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "disambiguation",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "targets",
+          "type": "Optional[list[str]]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "ip",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "city",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "country",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "state",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "iata",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "icao",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "unlocode",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "address",
+          "type": "Optional[str]"
         }
       ],
       "returns": "Json"
@@ -1411,6 +1471,84 @@
           "kind": "KEYWORD_ONLY",
           "name": "lang",
           "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "disambiguation",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "targets",
+          "type": "Optional[list[str]]"
+        }
+      ],
+      "returns": "Json"
+    },
+    "time.zones": {
+      "async": true,
+      "parameters": [
+        {
+          "default": null,
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "name": "query",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "country",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "area",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "offset",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "abbreviation",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "dst",
+          "type": "Optional[bool]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "observes_dst",
+          "type": "Optional[bool]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "at",
+          "type": "Optional[str]"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "details",
+          "type": "bool"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "sort",
+          "type": "Optional[str]"
         }
       ],
       "returns": "Json"
@@ -2948,6 +3086,66 @@
           "kind": "KEYWORD_ONLY",
           "name": "lang",
           "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "disambiguation",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "targets",
+          "type": "Optional[list[str]]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "ip",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "city",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "country",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "state",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "iata",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "icao",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "unlocode",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "address",
+          "type": "Optional[str]"
         }
       ],
       "returns": "Json"
@@ -2988,6 +3186,84 @@
           "kind": "KEYWORD_ONLY",
           "name": "lang",
           "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "disambiguation",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "targets",
+          "type": "Optional[list[str]]"
+        }
+      ],
+      "returns": "Json"
+    },
+    "time.zones": {
+      "async": false,
+      "parameters": [
+        {
+          "default": null,
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "name": "query",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "country",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "area",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "offset",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "abbreviation",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "dst",
+          "type": "Optional[bool]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "observes_dst",
+          "type": "Optional[bool]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "at",
+          "type": "Optional[str]"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "details",
+          "type": "bool"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "sort",
+          "type": "Optional[str]"
         }
       ],
       "returns": "Json"

{parseapi-1.3.0 → parseapi-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "parseapi"
-version = "1.3.0"
+version = "1.6.0"
 description = "Official ParseAPI client for Python. One key, minimal JSON, fast."
 readme = "README.md"
 license = "MIT"

{parseapi-1.3.0 → parseapi-1.6.0}/src/parseapi/__init__.py

@@ -2,5 +2,5 @@
 
 from ._client import AsyncParseAPI, ParseAPI, ParseAPIError
 
-__version__ = "1.3.0"
+__version__ = "1.6.0"
 __all__ = ["ParseAPI", "AsyncParseAPI", "ParseAPIError", "__version__"]

{parseapi-1.3.0 → parseapi-1.6.0}/src/parseapi/_client.py

@@ -10,7 +10,7 @@ from urllib.parse import quote
 
 import httpx
 
-VERSION = "1.3.0"
+VERSION = "1.6.0"
 _API_VERSION = "2.0.0"
 DEFAULT_BASE_URL = "https://api.parseapi.com"
 DEFAULT_TIMEOUT = 10.0
@@ -898,13 +898,21 @@ class _TimeSync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, timezone: Optional[str] = None, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False, lang: Optional[str] = None) -> Json:
-        """Current local time, UTC by default. With to, offsetless at is source wall time."""
-        path = "/time" if timezone is None else f"/time/{_seg(timezone)}"
-        return self._client._get(path, {"at": at, "to": to, "deep": deep, "lang": lang})
+    def __call__(self, timezone: Optional[str] = None, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False, lang: Optional[str] = None, disambiguation: Optional[str] = None, targets: Optional[list[str]] = None, ip: Optional[str] = None, city: Optional[str] = None, country: Optional[str] = None, state: Optional[str] = None, iata: Optional[str] = None, icao: Optional[str] = None, unlocode: Optional[str] = None, address: Optional[str] = None) -> Json:
+        """Current local time, UTC by default. With to or targets, offsetless at is source wall time.
+        disambiguation selects compatible (default), earlier, later, or reject at clock changes.
+        Explicit offsets select the instant directly."""
+        source = _time_source(timezone, ip=ip, city=city, country=country, state=state, iata=iata, icao=icao, unlocode=unlocode, address=address)
+        path = _time_path(timezone)
+        return self._client._get(path, {**source, "at": at, "to": to, "deep": deep, "lang": lang, "disambiguation": disambiguation, "targets": _time_targets(targets, to)})
 
-    def at(self, lat: float, lon: float, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False, lang: Optional[str] = None) -> Json:
-        return self._client._get("/time", {"lat": lat, "lon": lon, "at": at, "to": to, "deep": deep, "lang": lang})
+    def at(self, lat: float, lon: float, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False, lang: Optional[str] = None, disambiguation: Optional[str] = None, targets: Optional[list[str]] = None) -> Json:
+        return self._client._get("/time", {"lat": lat, "lon": lon, "at": at, "to": to, "deep": deep, "lang": lang, "disambiguation": disambiguation, "targets": _time_targets(targets, to)})
+
+
+    def zones(self, query: Optional[str] = None, *, country: Optional[str] = None, area: Optional[str] = None, offset: Optional[str] = None, abbreviation: Optional[str] = None, dst: Optional[bool] = None, observes_dst: Optional[bool] = None, at: Optional[str] = None, details: bool = False, sort: Optional[str] = None) -> Json:
+        """Search serving timezone IDs. Omit query to list all."""
+        return self._client._get("/time/zones", {"q": query, "country": country, "area": area, "offset": offset, "abbreviation": abbreviation, "dst": None if dst is None else str(dst).lower(), "observes_dst": None if observes_dst is None else str(observes_dst).lower(), "at": at, "details": details, "sort": sort})
 
 
 class _TimezoneSync:
@@ -938,13 +946,21 @@ class _TimeAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, timezone: Optional[str] = None, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False, lang: Optional[str] = None) -> Json:
-        """Current local time, UTC by default. With to, offsetless at is source wall time."""
-        path = "/time" if timezone is None else f"/time/{_seg(timezone)}"
-        return await self._client._get(path, {"at": at, "to": to, "deep": deep, "lang": lang})
+    async def __call__(self, timezone: Optional[str] = None, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False, lang: Optional[str] = None, disambiguation: Optional[str] = None, targets: Optional[list[str]] = None, ip: Optional[str] = None, city: Optional[str] = None, country: Optional[str] = None, state: Optional[str] = None, iata: Optional[str] = None, icao: Optional[str] = None, unlocode: Optional[str] = None, address: Optional[str] = None) -> Json:
+        """Current local time, UTC by default. With to or targets, offsetless at is source wall time.
+        disambiguation selects compatible (default), earlier, later, or reject at clock changes.
+        Explicit offsets select the instant directly."""
+        source = _time_source(timezone, ip=ip, city=city, country=country, state=state, iata=iata, icao=icao, unlocode=unlocode, address=address)
+        path = _time_path(timezone)
+        return await self._client._get(path, {**source, "at": at, "to": to, "deep": deep, "lang": lang, "disambiguation": disambiguation, "targets": _time_targets(targets, to)})
+
+    async def at(self, lat: float, lon: float, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False, lang: Optional[str] = None, disambiguation: Optional[str] = None, targets: Optional[list[str]] = None) -> Json:
+        return await self._client._get("/time", {"lat": lat, "lon": lon, "at": at, "to": to, "deep": deep, "lang": lang, "disambiguation": disambiguation, "targets": _time_targets(targets, to)})
 
-    async def at(self, lat: float, lon: float, *, at: Optional[str] = None, to: Optional[str] = None, deep: bool = False, lang: Optional[str] = None) -> Json:
-        return await self._client._get("/time", {"lat": lat, "lon": lon, "at": at, "to": to, "deep": deep, "lang": lang})
+
+    async def zones(self, query: Optional[str] = None, *, country: Optional[str] = None, area: Optional[str] = None, offset: Optional[str] = None, abbreviation: Optional[str] = None, dst: Optional[bool] = None, observes_dst: Optional[bool] = None, at: Optional[str] = None, details: bool = False, sort: Optional[str] = None) -> Json:
+        """Search serving timezone IDs. Omit query to list all."""
+        return await self._client._get("/time/zones", {"q": query, "country": country, "area": area, "offset": offset, "abbreviation": abbreviation, "dst": None if dst is None else str(dst).lower(), "observes_dst": None if observes_dst is None else str(observes_dst).lower(), "at": at, "details": details, "sort": sort})
 
 
 class _TimezoneAsync:
@@ -1004,3 +1020,28 @@ class _MeasureAsync:
     async def units(self, *, query: Optional[str] = None, type: Optional[str] = None, unit: Optional[str] = None, lang: Optional[str] = None) -> Json:
         """Discover reviewed units. unit filters compatible conversion targets."""
         return await self._client._get("/measure/units", {"q": query, "type": type, "unit": unit, "lang": lang})
+
+def _time_source(timezone, **values):
+    primary = [values.get(key) for key in ("ip", "city", "iata", "icao", "unlocode", "address") if values.get(key) is not None]
+    present = any(value is not None for value in values.values())
+    if (any(value is not None and (not isinstance(value, str) or not value.strip()) for value in values.values())
+        or (timezone is not None and present) or len(primary) > 1
+        or (values.get("country") is not None and primary and values.get("city") is None and values.get("address") is None)
+        or (values.get("state") is not None and ((values.get("city") is None and values.get("address") is None) or values.get("country") is None))
+        or (values.get("address") is not None and values.get("country") is None)):
+        raise ValueError('Pass one Time source, using country only with city or address and state only with city or address and country.')
+    return values
+
+
+def _time_path(timezone: Optional[str]) -> str:
+    if timezone is not None and timezone.strip().lower() in ("zones", "help"):
+        raise ValueError("Time source must be an IANA timezone ID. Use timezone discovery to list IDs.")
+    return "/time" if timezone is None else f"/time/{_seg(timezone)}"
+
+
+def _time_targets(targets: Optional[list[str]], to: Optional[str]) -> Optional[str]:
+    if targets is None:
+        return None
+    if to is not None or not isinstance(targets, (list, tuple)) or not 1 <= len(targets) <= 10 or any(not isinstance(zone, str) or not zone.strip() or ',' in zone for zone in targets):
+        raise ValueError("Time targets requires 1 to 10 timezone IDs and cannot be combined with to.")
+    return ','.join(targets)

{parseapi-1.3.0 → parseapi-1.6.0}/tests/test_client.py

@@ -23,6 +23,18 @@ def ok(body=None):
 
 
 URL_TABLE = [
+    (lambda p: p.time("America/New_York", at="2026-11-01T01:30:00", to="UTC", disambiguation="compatible"), "https://api.parseapi.com/time/America%2FNew_York?at=2026-11-01T01%3A30%3A00&to=UTC&disambiguation=compatible"),
+    (lambda p: p.time.at(40.71, -74.01, at="2026-11-01T01:30:00", to="UTC", disambiguation="compatible"), "https://api.parseapi.com/time?lat=40.71&lon=-74.01&at=2026-11-01T01%3A30%3A00&to=UTC&disambiguation=compatible"),
+    (lambda p: p.time("America/New_York", at="2026-11-01T01:30:00", to="UTC", disambiguation="earlier"), "https://api.parseapi.com/time/America%2FNew_York?at=2026-11-01T01%3A30%3A00&to=UTC&disambiguation=earlier"),
+    (lambda p: p.time.at(40.71, -74.01, at="2026-11-01T01:30:00", to="UTC", disambiguation="earlier"), "https://api.parseapi.com/time?lat=40.71&lon=-74.01&at=2026-11-01T01%3A30%3A00&to=UTC&disambiguation=earlier"),
+    (lambda p: p.time("America/New_York", at="2026-11-01T01:30:00", to="UTC", disambiguation="later"), "https://api.parseapi.com/time/America%2FNew_York?at=2026-11-01T01%3A30%3A00&to=UTC&disambiguation=later"),
+    (lambda p: p.time.at(40.71, -74.01, at="2026-11-01T01:30:00", to="UTC", disambiguation="later"), "https://api.parseapi.com/time?lat=40.71&lon=-74.01&at=2026-11-01T01%3A30%3A00&to=UTC&disambiguation=later"),
+    (lambda p: p.time("America/New_York", at="2026-11-01T01:30:00", to="UTC", disambiguation="reject"), "https://api.parseapi.com/time/America%2FNew_York?at=2026-11-01T01%3A30%3A00&to=UTC&disambiguation=reject"),
+    (lambda p: p.time.at(40.71, -74.01, at="2026-11-01T01:30:00", to="UTC", disambiguation="reject"), "https://api.parseapi.com/time?lat=40.71&lon=-74.01&at=2026-11-01T01%3A30%3A00&to=UTC&disambiguation=reject"),
+    (lambda p: p.time.zones(), "https://api.parseapi.com/time/zones"),
+    (lambda p: p.time.zones('Europe'), "https://api.parseapi.com/time/zones?q=Europe"),
+    (lambda p: p.time('UTC', targets=['UTC', 'Asia/Tokyo', 'UTC']), "https://api.parseapi.com/time/UTC?targets=UTC%2CAsia%2FTokyo%2CUTC"),
+    (lambda p: p.time.at(0, 0, targets=['UTC', 'Asia/Tokyo', 'UTC']), "https://api.parseapi.com/time?lat=0&lon=0&targets=UTC%2CAsia%2FTokyo%2CUTC"),
     (lambda p: p.bin("001234"), "https://api.parseapi.com/bin/001234"),
     (lambda p: p.bin("00 1234-56", deep=True), "https://api.parseapi.com/bin/00%201234-56?deep=true"),
     (lambda p: p.time(), "https://api.parseapi.com/time"),

parseapi-1.6.0/tests/test_postal_localities.py

@@ -0,0 +1,25 @@
+import asyncio
+
+import httpx
+import pytest
+
+from parseapi import AsyncParseAPI, ParseAPI
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+@pytest.mark.parametrize("extra", [
+    {}, {"localities": None}, {"localities": []},
+    {"localities": [{"city": "SYDNEY", "state": "NSW", "state_name": "New South Wales", "future": True}]},
+    {"localities": [{"city": "SYDNEY", "state": "NSW", "state_name": "New South Wales"}, {"city": "HAYMARKET", "state": "NSW", "state_name": "New South Wales"}]},
+])
+def test_postal_choices_preserve_observation_without_inferring_city(async_client, extra):
+    body = {"postal": "2000", "country": "AU", "city": None, **extra}
+    transport = httpx.MockTransport(lambda request: httpx.Response(200, json=body))
+    if async_client:
+        async def run():
+            async with AsyncParseAPI("test", transport=transport) as client:
+                assert await client.postal("2000", country="AU") == body
+        asyncio.run(run())
+    else:
+        with ParseAPI("test", transport=transport) as client:
+            assert client.postal("2000", country="AU") == body

parseapi-1.6.0/tests/test_time_complete.py

@@ -0,0 +1,54 @@
+import asyncio
+import httpx
+import pytest
+from parseapi import ParseAPI, AsyncParseAPI
+
+@pytest.mark.parametrize('async_mode', [False, True])
+def test_targets_validate_before_dispatch_and_preserve_observations(async_mode):
+    calls = []
+    payload = {'targets': None}
+    def handler(request):
+        calls.append(request)
+        return httpx.Response(200, json=payload)
+    async def run():
+        client_type = AsyncParseAPI if async_mode else ParseAPI
+        client = client_type('fixture', transport=httpx.MockTransport(handler), retries=0)
+        async def invoke(operation, *args, **kwargs):
+            result = operation(*args, **kwargs)
+            return await result if async_mode else result
+        try:
+            for targets in [[], [''], ['  '], ['UTC,UTC'], ['UTC'] * 11, [None], 'UTC']:
+                for method, args in [(client.time, ['UTC']), (client.time.at, [0, 0])]:
+                    with pytest.raises(ValueError):
+                        await invoke(method, *args, targets=targets)
+            with pytest.raises(ValueError):
+                await invoke(client.time, 'UTC', targets=['UTC'], to='UTC')
+            assert calls == []
+            for value in [None, [], [{'timezone': 'UTC', 'unix': 0}, {'timezone': 'UTC', 'unix': 0}]]:
+                payload['targets'] = value
+                assert await invoke(client.time, 'UTC', targets=['UTC', 'Asia/Tokyo', 'UTC']) == payload
+                assert calls[-1].url.params['targets'] == 'UTC,Asia/Tokyo,UTC'
+        finally:
+            if async_mode:
+                await client.close()
+            else:
+                client.close()
+    asyncio.run(run())
+
+
+@pytest.mark.parametrize('async_mode', [False, True])
+def test_reserved_time_source_does_not_call_discovery(async_mode):
+    calls = []
+    async def run():
+        cls = AsyncParseAPI if async_mode else ParseAPI
+        parse = cls('fixture', transport=httpx.MockTransport(lambda r: calls.append(r) or httpx.Response(200, json={})))
+        try:
+            for zone in ['zones', 'help', ' ZONES ', 'Help']:
+                with pytest.raises(ValueError, match='IANA timezone ID'):
+                    result = parse.time(zone)
+                    if async_mode: await result
+            assert calls == []
+        finally:
+            if async_mode: await parse.close()
+            else: parse.close()
+    asyncio.run(run())

parseapi-1.6.0/tests/test_time_gaps.py

@@ -0,0 +1,33 @@
+import asyncio
+import httpx
+import pytest
+from parseapi import ParseAPI, AsyncParseAPI
+RICH = {'timezone_database_version': '2026c', 'timezones': ['UTC'], 'at': '1970-01-01T00:00:00.000Z', 'zones': [{'timezone': 'UTC', 'countries': [], 'area': None, 'abbreviation': 'UTC', 'offset': '+00:00', 'offset_seconds': 0, 'dst': False, 'observes_dst': False}]}
+LOCATED = {'timezone': None, 'targets': None, 'location': {'input': {'type': 'city', 'value': 'Springfield'}, 'status': 'ambiguous', 'candidates': [{'id': 'city_a', 'name': 'Springfield', 'country': 'US', 'state': 'IL', 'timezone': 'America/Chicago', 'latitude': 0, 'longitude': 0}], 'truncated': False, 'source': 'city_reference'}, 'deep': {'standard_offset': '+01:00', 'standard_offset_seconds': 3600, 'dst_offset_seconds': -3600, 'season': {'start': {'at': '2026-10-25T01:00:00Z', 'before': {'offset_seconds': 3600, 'dst': False}, 'after': {'offset_seconds': 0, 'dst': True}, 'change_seconds': -3600}, 'end': None}}}
+@pytest.mark.parametrize('async_mode', [False, True])
+def test_time_explicit_locations_catalog_filters_and_observations(async_mode):
+    calls=[]
+    def handle(request):
+        calls.append(request)
+        return httpx.Response(200,json=RICH if request.url.path=='/time/zones' else LOCATED)
+    async def run():
+        client=(AsyncParseAPI if async_mode else ParseAPI)('fixture',transport=httpx.MockTransport(handle),retries=0)
+        async def call(method,*args,**kwargs):
+            result=method(*args,**kwargs)
+            return await result if async_mode else result
+        try:
+            assert await call(client.time.zones,country='US',area='America',offset='+00:00',abbreviation='UTC',dst=False,observes_dst=False,at='1970-01-01T00:00:00Z',details=True,sort='offset') == RICH
+            assert dict(calls[-1].url.params) == {'country': 'US', 'area': 'America', 'offset': '+00:00', 'abbreviation': 'UTC', 'dst': 'false', 'observes_dst': 'false', 'at': '1970-01-01T00:00:00Z', 'details': 'true', 'sort': 'offset'}
+            for source in [{'ip':'2001:db8::1'},{'city':'Springfield','country':'US','state':'IL'},{'country':'US'},{'iata':'JFK'},{'icao':'KJFK'},{'unlocode':'US NYC'},{'address':'1 Main Street','country':'US','state':'NY'}]:
+                assert await call(client.time,**source,targets=['UTC'],deep=True) == LOCATED
+                assert calls[-1].url.path == '/time'
+                for key,value in source.items(): assert calls[-1].url.params[key] == value
+            count=len(calls)
+            for source in [{'ip':'8.8.8.8','city':'Paris'},{'ip':'8.8.8.8','country':'US'},{'state':'NY'},{'city':'Paris','state':'IDF'},{'address':'a'},{'ip':''}]:
+                with pytest.raises(ValueError): await call(client.time,**source)
+            with pytest.raises(ValueError): await call(client.time,'UTC',city='Paris')
+            assert len(calls)==count
+        finally:
+            if async_mode: await client.close()
+            else: client.close()
+    asyncio.run(run())