tarifftrust 0.2.0__tar.gz → 0.3.1__tar.gz

{tarifftrust-0.2.0 → tarifftrust-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tarifftrust
-Version: 0.2.0
+Version: 0.3.1
 Summary: Official Python client for the TariffTrust API: every US import duty and fee for an HTS code, an origin and a value, each with its official source.
 Project-URL: Homepage, https://tarifftrust.com/api/
 Project-URL: Documentation, https://tarifftrust.com/api/reference/

{tarifftrust-0.2.0 → tarifftrust-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tarifftrust"
-version = "0.2.0"
+version = "0.3.1"
 description = "Official Python client for the TariffTrust API: every US import duty and fee for an HTS code, an origin and a value, each with its official source."
 readme = "README.md"
 requires-python = ">=3.10"

{tarifftrust-0.2.0 → tarifftrust-0.3.1}/src/tarifftrust/_operations.py

@@ -107,7 +107,8 @@ class Operations:
                 An informal entry pays a fixed fee the estimate does not calculate: it gives no
                 fees.
             facts: Answers to the questions of the facts catalogue (GET /v2/facts), by name. A
-                name outside the catalogue is said in warnings and never used.
+                name that is no question is refused, so that a typing error never gives a figure
+                on the ordinary case.
             freight: International freight in US dollars: no duty on it, it adds to the landed
                 cost.
             include_fees: Count the entry fees (MPF, HMF) of a declaration of this product
@@ -121,8 +122,10 @@ class Operations:
                 for KORUS…; GET /v2/agreements). Giving it declares that the goods meet its
                 rules of origin and that you hold the proof.
             publication_id: Calculate with this publication of the rules instead of the one in
-                service on that date: the data.publication_id of an earlier answer gives the
-                same result again, as long as the engine has not changed.
+                service on that date: the data.publication_id of an earlier answer gives its
+                rates and rules again, as long as the engine has not changed. What withholds an
+                estimate today (an incident, an official notice not yet read, an exclusion from
+                importation) still applies: a saved estimate alone keeps its result.
             quantities: Quantities in the units a duty counts (kg, l, item, dozen, pair,
                 proof_liter…), nonnegative. An answer names the quantity it needs in missing
                 ("quantities.kg").
@@ -167,8 +170,10 @@ class Operations:
         Args:
             items: The products, each calculated on its own.
             publication_id: Calculate with this publication of the rules instead of the one in
-                service on that date: the data.publication_id of an earlier answer gives the
-                same result again, as long as the engine has not changed.
+                service on that date: the data.publication_id of an earlier answer gives its
+                rates and rules again, as long as the engine has not changed. What withholds an
+                estimate today (an incident, an official notice not yet read, an exclusion from
+                importation) still applies: a saved estimate alone keeps its result.
             idempotency_key: Makes a retry of this call safe; a new one is generated for each
                 call otherwise.
         """
@@ -213,8 +218,9 @@ class Operations:
             entry_type: A formal entry pays the merchandise processing fee (MPF) on its value.
                 An informal entry pays a fixed fee the estimate does not calculate: it gives no
                 fees.
-            facts: Answers that hold for the whole declaration (GET /v2/facts, scope entry or
-                shipment).
+            facts: Answers that hold for every line of the declaration, by name (GET /v2/facts):
+                a line's own answer comes first. Given here, mpf_exempt holds for the lines
+                entered under an agreement, and hmf_exempt for the declaration.
             freight: International freight in US dollars: no duty on it, it adds to the landed
                 cost.
             include_fees: Count the entry fees (MPF, HMF) of the declaration.
@@ -222,8 +228,10 @@ class Operations:
                 landed cost.
             label: A name for the saved estimate; needs save.
             publication_id: Calculate with this publication of the rules instead of the one in
-                service on that date: the data.publication_id of an earlier answer gives the
-                same result again, as long as the engine has not changed.
+                service on that date: the data.publication_id of an earlier answer gives its
+                rates and rules again, as long as the engine has not changed. What withholds an
+                estimate today (an incident, an official notice not yet read, an exclusion from
+                importation) still applies: a saved estimate alone keeps its result.
             reference: Your reference for the declaration.
             save: Save the estimate: only a saved estimate keeps its detail, is reported, and is
                 notified if a rate proves wrong. An answer without a figure is not saved. Send
@@ -282,7 +290,8 @@ class Operations:
                 An informal entry pays a fixed fee the estimate does not calculate: it gives no
                 fees.
             facts: Answers to the questions of the facts catalogue (GET /v2/facts), by name. A
-                name outside the catalogue is said in warnings and never used.
+                name that is no question is refused, so that a typing error never gives a figure
+                on the ordinary case.
             freight: International freight in US dollars: no duty on it, it adds to the landed
                 cost.
             from_: First day of the period. Unset: the first edition the service holds.
@@ -318,10 +327,10 @@ class Operations:
     ) -> FactList:
         """List the questions an estimate may ask.
 
-        The facts catalogue: each question a measure may depend on, by the name to answer it
-        with in facts, its type, its choices and its ordinary case. An answer names the ones it
-        needs in missing, and those it rests on in facts. Needs the read permission; not
-        counted.
+        The questions that can change an answer today: each by the name to answer it with in
+        facts, its type, its choices and its ordinary case. An answer names the ones it needs in
+        missing, and those it rests on in facts. The example shows two of them; the answer lists
+        them all. Needs the read permission; not counted.
         """
         return self._request(
             "GET",
@@ -510,7 +519,8 @@ class AsyncOperations:
                 An informal entry pays a fixed fee the estimate does not calculate: it gives no
                 fees.
             facts: Answers to the questions of the facts catalogue (GET /v2/facts), by name. A
-                name outside the catalogue is said in warnings and never used.
+                name that is no question is refused, so that a typing error never gives a figure
+                on the ordinary case.
             freight: International freight in US dollars: no duty on it, it adds to the landed
                 cost.
             include_fees: Count the entry fees (MPF, HMF) of a declaration of this product
@@ -524,8 +534,10 @@ class AsyncOperations:
                 for KORUS…; GET /v2/agreements). Giving it declares that the goods meet its
                 rules of origin and that you hold the proof.
             publication_id: Calculate with this publication of the rules instead of the one in
-                service on that date: the data.publication_id of an earlier answer gives the
-                same result again, as long as the engine has not changed.
+                service on that date: the data.publication_id of an earlier answer gives its
+                rates and rules again, as long as the engine has not changed. What withholds an
+                estimate today (an incident, an official notice not yet read, an exclusion from
+                importation) still applies: a saved estimate alone keeps its result.
             quantities: Quantities in the units a duty counts (kg, l, item, dozen, pair,
                 proof_liter…), nonnegative. An answer names the quantity it needs in missing
                 ("quantities.kg").
@@ -570,8 +582,10 @@ class AsyncOperations:
         Args:
             items: The products, each calculated on its own.
             publication_id: Calculate with this publication of the rules instead of the one in
-                service on that date: the data.publication_id of an earlier answer gives the
-                same result again, as long as the engine has not changed.
+                service on that date: the data.publication_id of an earlier answer gives its
+                rates and rules again, as long as the engine has not changed. What withholds an
+                estimate today (an incident, an official notice not yet read, an exclusion from
+                importation) still applies: a saved estimate alone keeps its result.
             idempotency_key: Makes a retry of this call safe; a new one is generated for each
                 call otherwise.
         """
@@ -616,8 +630,9 @@ class AsyncOperations:
             entry_type: A formal entry pays the merchandise processing fee (MPF) on its value.
                 An informal entry pays a fixed fee the estimate does not calculate: it gives no
                 fees.
-            facts: Answers that hold for the whole declaration (GET /v2/facts, scope entry or
-                shipment).
+            facts: Answers that hold for every line of the declaration, by name (GET /v2/facts):
+                a line's own answer comes first. Given here, mpf_exempt holds for the lines
+                entered under an agreement, and hmf_exempt for the declaration.
             freight: International freight in US dollars: no duty on it, it adds to the landed
                 cost.
             include_fees: Count the entry fees (MPF, HMF) of the declaration.
@@ -625,8 +640,10 @@ class AsyncOperations:
                 landed cost.
             label: A name for the saved estimate; needs save.
             publication_id: Calculate with this publication of the rules instead of the one in
-                service on that date: the data.publication_id of an earlier answer gives the
-                same result again, as long as the engine has not changed.
+                service on that date: the data.publication_id of an earlier answer gives its
+                rates and rules again, as long as the engine has not changed. What withholds an
+                estimate today (an incident, an official notice not yet read, an exclusion from
+                importation) still applies: a saved estimate alone keeps its result.
             reference: Your reference for the declaration.
             save: Save the estimate: only a saved estimate keeps its detail, is reported, and is
                 notified if a rate proves wrong. An answer without a figure is not saved. Send
@@ -685,7 +702,8 @@ class AsyncOperations:
                 An informal entry pays a fixed fee the estimate does not calculate: it gives no
                 fees.
             facts: Answers to the questions of the facts catalogue (GET /v2/facts), by name. A
-                name outside the catalogue is said in warnings and never used.
+                name that is no question is refused, so that a typing error never gives a figure
+                on the ordinary case.
             freight: International freight in US dollars: no duty on it, it adds to the landed
                 cost.
             from_: First day of the period. Unset: the first edition the service holds.
@@ -721,10 +739,10 @@ class AsyncOperations:
     ) -> FactList:
         """List the questions an estimate may ask.
 
-        The facts catalogue: each question a measure may depend on, by the name to answer it
-        with in facts, its type, its choices and its ordinary case. An answer names the ones it
-        needs in missing, and those it rests on in facts. Needs the read permission; not
-        counted.
+        The questions that can change an answer today: each by the name to answer it with in
+        facts, its type, its choices and its ordinary case. An answer names the ones it needs in
+        missing, and those it rests on in facts. The example shows two of them; the answer lists
+        them all. Needs the read permission; not counted.
         """
         return await self._request(
             "GET",

{tarifftrust-0.2.0 → tarifftrust-0.3.1}/src/tarifftrust/_version.py

@@ -1,3 +1,3 @@
 """The package's version, the one in pyproject.toml."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"

{tarifftrust-0.2.0 → tarifftrust-0.3.1}/src/tarifftrust/types.py

@@ -38,8 +38,9 @@ class BatchItem(_BatchItemRequired, total=False):
     pays a fixed fee the estimate does not calculate: it gives no fees.
     """
     facts: Mapping[str, int | float | Decimal | str | bool]
-    """Answers to the questions of the facts catalogue (GET /v2/facts), by name. A name outside
-    the catalogue is said in warnings and never used.
+    """Answers to the questions of the facts catalogue (GET /v2/facts), by name. A name that is
+    no question is refused, so that a typing error never gives a figure on the ordinary
+    case.
     """
     freight: int | float | Decimal | str
     """International freight in US dollars: no duty on it, it adds to the landed cost."""
@@ -86,12 +87,14 @@ class _LineInputRequired(TypedDict):
 class LineInput(_LineInputRequired, total=False):
     """One line of a declaration."""
     customs_value: int | float | Decimal | str | None
-    """Customs value in US dollars: the transaction value declared, not a retail price. Unset:
-    the duty rate is given, and an amount only where the duty does not depend on the value.
+    """Customs value in US dollars: the transaction value declared, not a retail price. A
+    declaration's line asks for it, the fees resting on it: without it, the line gives no
+    rate and no amount.
     """
     facts: Mapping[str, int | float | Decimal | str | bool]
-    """Answers to the questions of the facts catalogue (GET /v2/facts), by name. A name outside
-    the catalogue is said in warnings and never used.
+    """Answers to the questions of the facts catalogue (GET /v2/facts), by name. A name that is
+    no question is refused, so that a typing error never gives a figure on the ordinary
+    case.
     """
     preference: str | None
     """A trade agreement's symbol from the HTS special column (S for USMCA, KR for KORUS…; GET
@@ -142,6 +145,24 @@ class AgreementList(Model):
     """Where the tariff that names them is published."""
 
 
+class AskedBy(Model):
+    """An official text that asks a question: read it to answer precisely."""
+
+    _fields: ClassVar[frozenset[str]] = frozenset(['heading', 'title', 'url'])
+    _required: ClassVar[frozenset[str]] = frozenset(['heading', 'title', 'url'])
+
+    heading: str | None
+    """The Chapter 99 heading, or the tariff line, whose text asks it; null for a regulation."""
+
+    title: str
+    """What it is, in words."""
+
+    url: str
+    """Where to read it: the heading's page, with its text and the note it cites, or the
+    official document of a notice read ahead of the tariff.
+    """
+
+
 class AuditedDeclaration(Model):
     """A saved declaration's answer, with the detail behind it."""
 
@@ -253,8 +274,9 @@ class AuditedEstimate(Model):
     """All the duties, in US dollars. Null is unknown, never zero."""
 
     estimated_duty_rate: str | None
-    """The duties as a fraction of the customs value: 0.365 is 36.5%. Without a value, the sum
-    of the rates; null when a duty is not a percentage, or while a duty is withheld.
+    """The duties as a fraction of the customs value: 0.365 is 36.5%. The sum of the rates when
+    each duty is a percentage, with or without a value; else the duties over the value, to 4
+    places, null without a value. Null while a duty is withheld.
     """
 
     estimated_fees: str | None
@@ -349,8 +371,9 @@ class AuditedLine(Model):
     """All the duties, in US dollars. Null is unknown, never zero."""
 
     estimated_duty_rate: str | None
-    """The duties as a fraction of the customs value: 0.365 is 36.5%. Without a value, the sum
-    of the rates; null when a duty is not a percentage, or while a duty is withheld.
+    """The duties as a fraction of the customs value: 0.365 is 36.5%. The sum of the rates when
+    each duty is a percentage, else the duties over the value, to 4 places. Null while a
+    duty is withheld.
     """
 
     facts: dict[str, Any] | None
@@ -660,8 +683,9 @@ class Estimate(Model):
     """All the duties, in US dollars. Null is unknown, never zero."""
 
     estimated_duty_rate: str | None
-    """The duties as a fraction of the customs value: 0.365 is 36.5%. Without a value, the sum
-    of the rates; null when a duty is not a percentage, or while a duty is withheld.
+    """The duties as a fraction of the customs value: 0.365 is 36.5%. The sum of the rates when
+    each duty is a percentage, with or without a value; else the duties over the value, to 4
+    places, null without a value. Null while a duty is withheld.
     """
 
     estimated_fees: str | None
@@ -746,16 +770,25 @@ class FactChoice(Model):
 class FactDefinition(Model):
     """A question an estimate may ask about the goods or the declaration."""
 
-    _fields: ClassVar[frozenset[str]] = frozenset(['choices', 'default', 'help', 'name', 'question', 'scope', 'type', 'unit'])
+    _fields: ClassVar[frozenset[str]] = frozenset(['asked_by', 'choices', 'default', 'help', 'name', 'question', 'scope', 'type', 'unit'])
     _required: ClassVar[frozenset[str]] = frozenset(['help', 'name', 'question', 'scope', 'type'])
-    _nested: ClassVar[dict[str, Any]] = {'choices': ['FactChoice']}
-    _defaults: ClassVar[dict[str, Any]] = {'choices': [], 'unit': ''}
+    _nested: ClassVar[dict[str, Any]] = {'asked_by': ['AskedBy'], 'choices': ['FactChoice']}
+    _defaults: ClassVar[dict[str, Any]] = {'asked_by': [], 'choices': [], 'unit': ''}
+
+    asked_by: list[AskedBy]
+    """The official texts that ask it today: the headings whose rules in service read it, or
+    the regulation of a fee. Empty for what depends on each product's own line (its rate,
+    its entry); an estimate names, in missing, those that ask it for its goods.
+    """
 
     choices: list[FactChoice]
     """For a choice: the values to choose from."""
 
     default: Any
-    """The ordinary case, supposed when unanswered."""
+    """The ordinary case, supposed when unanswered. For an amount, "customs_value": the whole
+    customs value of the line; for a country, "origin": the origin of the line. Send a
+    value, never these names.
+    """
 
     help: str
     """What it means, and how to answer it."""
@@ -773,7 +806,7 @@ class FactDefinition(Model):
 
     type: str
     """How it is answered: boolean (true or false), choice (one of choices), money (US
-    dollars), number, country (ISO code) or heading (a Chapter 99 heading).
+    dollars), number or country (ISO code).
     """
 
     unit: str
@@ -781,14 +814,14 @@ class FactDefinition(Model):
 
 
 class FactList(Model):
-    """The facts catalogue: every question an estimate may ask."""
+    """The questions an estimate may ask."""
 
     _fields: ClassVar[frozenset[str]] = frozenset(['facts'])
     _required: ClassVar[frozenset[str]] = frozenset(['facts'])
     _nested: ClassVar[dict[str, Any]] = {'facts': ['FactDefinition']}
 
     facts: list[FactDefinition]
-    """Every question of the catalogue."""
+    """The questions that can change an answer today."""
 
 
 class HistoryPoint(Model):
@@ -822,8 +855,9 @@ class HistoryPoint(Model):
     """All the duties, in US dollars. Null is unknown, never zero."""
 
     estimated_duty_rate: str | None
-    """The duties as a fraction of the customs value: 0.365 is 36.5%. Without a value, the sum
-    of the rates; null when a duty is not a percentage, or while a duty is withheld.
+    """The duties as a fraction of the customs value: 0.365 is 36.5%. The sum of the rates when
+    each duty is a percentage, with or without a value; else the duties over the value, to 4
+    places, null without a value. Null while a duty is withheld.
     """
 
     estimated_fees: str | None
@@ -1076,8 +1110,9 @@ class Line(Model):
     """All the duties, in US dollars. Null is unknown, never zero."""
 
     estimated_duty_rate: str | None
-    """The duties as a fraction of the customs value: 0.365 is 36.5%. Without a value, the sum
-    of the rates; null when a duty is not a percentage, or while a duty is withheld.
+    """The duties as a fraction of the customs value: 0.365 is 36.5%. The sum of the rates when
+    each duty is a percentage, else the duties over the value, to 4 places. Null while a
+    duty is withheld.
     """
 
     facts: dict[str, Any] | None
@@ -1122,8 +1157,12 @@ class Line(Model):
 class MissingField(Model):
     """What the service needs to give a figure."""
 
-    _fields: ClassVar[frozenset[str]] = frozenset(['choices', 'field', 'question', 'type', 'unit'])
+    _fields: ClassVar[frozenset[str]] = frozenset(['asked_by', 'choices', 'field', 'question', 'type', 'unit'])
     _required: ClassVar[frozenset[str]] = frozenset(['field', 'question', 'type'])
+    _nested: ClassVar[dict[str, Any]] = {'asked_by': ['AskedBy']}
+
+    asked_by: list[AskedBy] | None
+    """The official texts that ask it for these goods, to answer it precisely."""
 
     choices: list[Any] | None
     """The values a choice takes."""
@@ -1135,9 +1174,7 @@ class MissingField(Model):
     """What it asks, in words."""
 
     type: str
-    """The type of its value: number, money, boolean, choice, text, heading, country or
-    datetime.
-    """
+    """The type of its value: number, money, boolean, choice, text, country or datetime."""
 
     unit: str | None
     """The unit of a quantity."""

{tarifftrust-0.2.0 → tarifftrust-0.3.1}/uv.lock

@@ -456,7 +456,7 @@ wheels = [
 
 [[package]]
 name = "tarifftrust"
-version = "0.2.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },