Readers

Converting simple structured data from XML or JSON into authorityspoke objects.

These functions will usually be called by functions from the io.loaders module after they import some data from a file.

authorityspoke.io.readers.read_enactment(enactment_dict, code=None, mentioned=None, regime=None, report_mentioned=False, **kwargs)

Create a new Enactment object using imported JSON data.

The new Enactment can be composed from a Code referenced in the regime parameter.

Parameters
Return type

Union[Enactment, Tuple[Enactment, Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]]

Returns

a new Enactment object, optionally with text links.

authorityspoke.io.readers.read_enactments(record_list, mentioned=None, regime=None, report_mentioned=False)

Create a new Enactment object using imported JSON data.

The new Enactment can be composed from a Code referenced in the regime parameter.

Parameters
Return type

Union[Tuple[Enactment, …], Tuple[Tuple[Enactment, …], Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]]

Returns

a list of new Enactment objects, optionally with text links.

authorityspoke.io.readers.get_references_from_mentioned(content, mentioned, placeholder='{}')

Retrieve known context Factors for new Fact.

Parameters
  • content (str) – the content for the Fact’s Predicate.

  • mentioned (Dict[Union[Factor, Enactment], List[TextQuoteSelector]]) – list of Factors with names that could be referenced in content

  • placeholder (str) – a string to replace the names of referenced Factors in content

Return type

Tuple[str, List[Union[Enactment, Factor]]]

Returns

the content string with any referenced Factors replaced by placeholder, and a list of referenced Factors in the order they appeared in content.

authorityspoke.io.readers.read_quantity(quantity)

Create pint quantity object from text.

Parameters

quantity (str) – when a string is being parsed for conversion to a Predicate, this is the part of the string after the equals or inequality sign.

Return type

Union[float, int, Quantity]

Returns

a Python number object or a Quantity object created with pint.UnitRegistry.

authorityspoke.io.readers.get_references_from_string(content, mentioned)

Make Entity context Factors from string.

This function identifies context Factors by finding brackets around them, while get_references_from_mentioned() depends on knowing the names of the context factors in advance. Also, this function works only when all the context_factors are type Entity.

Despite “placeholder” being defined as a variable elsewhere, this function isn’t compatible with any placeholder string other than “{}”.

Parameters
  • content (str) – a string containing a clause making an assertion. Curly brackets surround the names of Entity context factors to be created.

  • content – a TextLinkDict of known Factors. It will not be searched for Factors to add to context_factors, but newly created Entity object will be added to it.

Return type

Tuple[str, List[Entity], Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]

Returns

a Predicate and Entity objects from a string that has curly brackets around the context factors and the comparison/quantity.

authorityspoke.io.readers.read_fact(content='', truth=True, reciprocal=False, standard_of_proof=None, name=None, mentioned=None, report_mentioned=False, absent=False, generic=False, **kwargs)

Construct a Fact from strings and bools.

Parameters
  • content (str) – a string containing a clause making an assertion.

  • truth (bool) – whether the assertion in content is claimed to be true

  • reciprocal (bool) – whether the order of the first two entities in content can be changed without changing the meaning

  • mentioned (Optional[Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]) – a list of Factors that may be included by reference to their names.

  • standard_of_proof (Optional[str]) – the finding as to the strength of the evidence supporting the assertion, if any

  • name (Optional[str]) – a string identifier

  • mentioned – known Factors. Can be reused.

  • report_mentioned (bool) – if True, return a new TextLinkDict in addition to the Fact.

  • absent (bool) – whether the Fact can be considered absent from the case

  • generic (bool) – whether the Fact is interchangeable with other generic facts without changing the meaning of a Rule where it is mentioned

Return type

Union[Fact, Tuple[Fact, Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]]

Returns

a Fact, with optional mentioned factors

authorityspoke.io.readers.subclass_from_str(name)

Find class for use in JSON deserialization process.

Obtains a classname of a Factor subclass from a string. The list of subclasses used here must be updated wheneven a new one is created.

Parameters

name (str) – name of the desired subclass.

Return type

Type[+CT_co]

Returns

the Class named name.

authorityspoke.io.readers.read_factor(factor_record, mentioned=None, report_mentioned=False, **kwargs)

Turn fields from a chunk of JSON into a Factor object.

Parameters
  • factor_record (Dict[~KT, ~VT]) – parameter values to pass to Factor.__init__().

  • mentioned (Optional[Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]) – a list of relevant Factors that have already been constructed and can be used in composition of the output Factor, instead of constructing new ones.

Return type

Union[Factor, None, Tuple[Optional[Factor], Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]]

authorityspoke.io.readers.read_holding(outputs, inputs=None, despite=None, exclusive=False, rule_valid=True, decided=True, mandatory=False, universal=False, generic=False, enactments=None, enactments_despite=None, anchors=None, mentioned=None, regime=None, report_mentioned=False)

Create new Holding object from simple datatypes from JSON input.

Will yield multiple items if exclusive: True is present in record.

Parameters
  • inputs (Union[str, Dict[~KT, ~VT], List[Union[str, Dict[~KT, ~VT]]], None]) – data for constructing Factor inputs for a Rule

  • despite (Union[str, Dict[~KT, ~VT], List[Union[str, Dict[~KT, ~VT]]], None]) – data for constructing despite Factors for a Rule

  • outputs (Union[str, Dict[~KT, ~VT], List[Union[str, Dict[~KT, ~VT]]], None]) – data for constructing Factor outputs for a Rule

  • enactments (Union[Dict[~KT, ~VT], Iterable[Dict[~KT, ~VT]], None]) – the Enactments cited as authority for invoking the procedure.

  • enactments_despite (Union[Dict[~KT, ~VT], Iterable[Dict[~KT, ~VT]], None]) – the Enactments specifically cited as failing to preclude application of the procedure.

  • mandatory (bool) – whether the procedure is mandatory for the court to apply whenever the Rule is properly invoked. False means that the procedure is “discretionary”.

  • universal (bool) – True if the procedure is applicable whenever its inputs are present. False means that the procedure is applicable in “some” situation where the inputs are present.

  • generic (bool) – whether the Rule is being mentioned in a generic context. e.g., if the Rule is being mentioned in an Argument object merely as an example of the kind of Rule that might be mentioned in such an Argument.

  • name – an identifier used to retrieve the Rule when needed for the composition of another Factor object.

  • rule_valid (bool) – Whether the Rule is asserted to be valid (or useable by a court in litigation).

  • decided (bool) – Whether it should be deemed decided whether the Rule is valid. If not, the Holding have the effect of overruling prior Holdings finding the Rule to be either valid or invalid.

  • anchors (Union[str, Dict[~KT, ~VT], Iterable[Union[str, Dict[~KT, ~VT]]], None]) – Text selectors for the whole Holding, not for any individual Factor. Often selects text used to indicate whether the Rule is mandatory, universal, valid, or decided, or shows the exclusive way to reach the outputs.

  • mentioned (Optional[Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]) – Known Factors that may be reused in constructing the new Holding.

  • regime (Optional[Regime]) – Collection of Jurisdictions and corresponding Codes for discovering Enactments to reference in the new Holding.

Return type

Iterator[Union[Holding, Tuple[Holding, Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]]]

Returns

New Holding, and an updated dictionary with mentioned Factors as keys and their TextQuoteSelectors as values.

authorityspoke.io.readers.read_holdings(holdings, regime=None, mentioned=None, report_mentioned=False)

Load a list of Holdingss from JSON, with optional text links.

Parameters
Parame regime

A collection of Jurisdictions and the Codes that have been enacted in each. Used for constructing Enactments referenced by Holdings.

Return type

Union[List[Holding], Tuple[List[Holding], Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]]

Returns

a list of Holding objects, optionally with an index matching Factors to selectors.

authorityspoke.io.readers.read_case(decision_dict, lead_only=True, as_generator=False)

Create and return one or more Opinion objects from a dict API response.

Relies on the JSON format from the Caselaw Access Project API.

This function is a more convenient way to call read_opinions with an entire case from the CAP API as a single parameter.

Parameters
  • decision_dict (Dict[str, Any]) – A dict created from a Caselaw Access Project API response.

  • lead_only (bool) – If True, returns a single Opinion object, otherwise returns an iterator that yields every Opinion in the case.

  • as_generator (bool) – if True, returns a generator that yields all opinions meeting the query.

Return type

Union[Opinion, Iterator[Opinion], List[Opinion]]

authorityspoke.io.readers.read_opinions(citations, decision_date, court, casebody=None, name='', name_abbreviation='', first_page='', last_page='', lead_only=True, as_generator=False, **kwargs)

Create and return one or more Opinion objects.

This function uses the model of a judicial decision from the Caselaw Access Project API. One of these records may contain multiple Opinions.

Typically one record will contain all the Opinions from one appeal, but not necessarily from the whole lawsuit. One lawsuit may contain multiple appeals or other petitions, and if more then one of those generates published Opinions, the CAP API will divide those Opinions into a separate record for each appeal.

The lead opinion is commonly, but not always, the only Opinion that creates binding legal authority. Usually every Rule posited by the lead Opinion is binding, but some may not be, often because parts of the Opinion fail to command a majority of the panel of judges.

Parameters
  • citations (List[Dict[str, str]]) – Page references that would be used to locate the decision in printed volumes. May be the closest things to accepted identifiers for a decision.

  • casebody (Optional[Dict[~KT, ~VT]]) – A large section of the CAP API response containing all the text that was printed in the reporter volume. Only available if the full_case flag was used in the API request.

  • decision_date (str) – The day the Opinions were issued, in ISO format.

  • court (Dict[str, Union[str, int]]) – A dict containing the Court slug, hopefully a unique identifier of the court. Also contains the “id”, which can be resorted to when the slug turns out not to be unique.

  • name (str) – Full name of the lawsuit. Sometimes the same lawsuit may change its name as time passes between multiple appeals.

  • name_abbreviation (str) – A shorter name for the lawsuit. Courts may or may not have deterministic rules for creating the abbreviation given the full name. This may be only one of many possible abbreviations.

  • first_page (str) – The first printed page where any of the Opinions for this decision can be found. Does not come with an identifier of the reporter, but in most cases there is only one official reporter, which is the most likely choice.

  • last_page (str) – The last printed page where any of the Opinions for this decision can be found.

  • lead_only (bool) – If True, returns a single Opinion object from the first opinion found in the casebody/data/opinions section of the dict, which should usually be the lead opinion. If False, returns an iterator that yields Opinion objects from every opinion in the case.

Return type

Union[Opinion, Iterator[Opinion], List[Opinion]]

authorityspoke.io.readers.read_rule(outputs, inputs=None, despite=None, mandatory=False, universal=False, generic=False, enactments=None, enactments_despite=None, mentioned=None, regime=None, report_mentioned=False)

Make Rule from a dict of strings and a list of mentioned Factors.

Parameters
  • inputs (Union[str, Dict[~KT, ~VT], List[Union[str, Dict[~KT, ~VT]]], None]) – data for constructing Factor inputs for a Rule

  • despite (Union[str, Dict[~KT, ~VT], List[Union[str, Dict[~KT, ~VT]]], None]) – data for constructing despite Factors for a Rule

  • outputs (Union[str, Dict[~KT, ~VT], List[Union[str, Dict[~KT, ~VT]]], None]) – data for constructing Factor outputs for a Rule

  • enactments (Union[Dict[~KT, ~VT], Iterable[Dict[~KT, ~VT]], None]) – the Enactments cited as authority for invoking the procedure.

  • enactments_despite (Union[Dict[~KT, ~VT], Iterable[Dict[~KT, ~VT]], None]) – the Enactments specifically cited as failing to preclude application of the procedure.

  • mandatory (bool) – whether the procedure is mandatory for the court to apply whenever the Rule is properly invoked. False means that the procedure is “discretionary”.

  • universal (bool) – True if the procedure is applicable whenever its inputs are present. False means that the procedure is applicable in “some” situation where the inputs are present.

  • generic (bool) – whether the Rule is being mentioned in a generic context. e.g., if the Rule is being mentioned in an Argument object merely as an example of the kind of Rule that might be mentioned in such an Argument.

  • mentioned (Optional[Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]) – a series of context factors, including any generic Factors that need to be mentioned in Predicates. These will have been constructed from the mentioned_entities section of the input JSON.

  • regime (Optional[Regime]) –

Return type

Union[Rule, Tuple[Rule, Dict[Union[Factor, Enactment], List[TextQuoteSelector]]]]

Returns

iterator yielding Rules with the items from mentioned_entities as context_factors