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.
Create a new
Enactment
object using imported JSON data.The new
Enactment
can be composed from aCode
referenced in theregime
parameter.- Parameters
enactment_dict (
Dict
[str
,str
]) –dict
with string fields from JSON for constructing newEnactment
code (
Optional
[Code
]) – theCode
that is the source for thisEnactment
mentioned (
Optional
[Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]) –TextLinkDict
for knownFactor
s andEnactment
sregime (
Optional
[Regime
]) – theRegime
where theCode
that is the source for thisEnactment
can be found, or where it should be addedreport_mentioned (
bool
) – if True, return a newTextLinkDict
in addition to theEnactment
.
- Return type
Union
[Enactment
,Tuple
[Enactment
,Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]]- Returns
a new
Enactment
object, optionally with text links.
Create a new
Enactment
object using imported JSON data.The new
Enactment
can be composed from aCode
referenced in theregime
parameter.- Parameters
record_list (
Union
[Dict
[str
,str
],List
[Dict
[str
,str
]]]) – sequence ofdict
s with string fields from JSON for constructing newEnactment
scode – the
Code
that is the source for thisEnactment
mentioned (
Optional
[Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]) –TextLinkDict
for knownFactor
s andEnactment
sregime (
Optional
[Regime
]) – theRegime
where theCode
that is the source for thisEnactment
can be found, or where it should be addedreport_mentioned (
bool
) – if True, return a newTextLinkDict
in addition to theEnactment
.
- 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.
Retrieve known context
Factor
s for newFact
.- Parameters
- Return type
- Returns
the content string with any referenced
Factor
s replaced by placeholder, and a list of referencedFactor
s in the order they appeared in content.
Create pint quantity object from text.
- Parameters
quantity (
str
) – when a string is being parsed for conversion to aPredicate
, this is the part of the string after the equals or inequality sign.- Return type
- Returns
a Python number object or a
Quantity
object created with pint.UnitRegistry.
Make
Entity
contextFactor
s from string.This function identifies context
Factor
s by finding brackets around them, whileget_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 typeEntity
.Despite “placeholder” being defined as a variable elsewhere, this function isn’t compatible with any placeholder string other than “{}”.
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 truereciprocal (
bool
) – whether the order of the first two entities in content can be changed without changing the meaningmentioned (
Optional
[Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]) – a list ofFactor
s that may be included by reference to theirname
s.standard_of_proof (
Optional
[str
]) – the finding as to the strength of the evidence supporting the assertion, if anymentioned – known
Factors
. Can be reused.report_mentioned (
bool
) – if True, return a newTextLinkDict
in addition to theFact
.absent (
bool
) – whether theFact
can be considered absent from the casegeneric (
bool
) – whether theFact
is interchangeable with other generic facts without changing the meaning of aRule
where it is mentioned
- Return type
Union
[Fact
,Tuple
[Fact
,Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]]- Returns
a
Fact
, with optional mentioned factors
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.
Turn fields from a chunk of JSON into a
Factor
object.- Parameters
factor_record (
Dict
[~KT, ~VT]) – parameter values to pass toFactor.__init__()
.mentioned (
Optional
[Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]) – a list of relevantFactor
s that have already been constructed and can be used in composition of the outputFactor
, instead of constructing new ones.
- Return type
Union
[Factor
,None
,Tuple
[Optional
[Factor
],Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]]
Create new
Holding
object from simple datatypes from JSON input.Will yield multiple items if
exclusive: True
is present inrecord
.- Parameters
inputs (
Union
[str
,Dict
[~KT, ~VT],List
[Union
[str
,Dict
[~KT, ~VT]]],None
]) – data for constructingFactor
inputs for aRule
despite (
Union
[str
,Dict
[~KT, ~VT],List
[Union
[str
,Dict
[~KT, ~VT]]],None
]) – data for constructing despiteFactor
s for aRule
outputs (
Union
[str
,Dict
[~KT, ~VT],List
[Union
[str
,Dict
[~KT, ~VT]]],None
]) – data for constructingFactor
outputs for aRule
enactments (
Union
[Dict
[~KT, ~VT],Iterable
[Dict
[~KT, ~VT]],None
]) – theEnactment
s cited as authority for invoking theprocedure
.enactments_despite (
Union
[Dict
[~KT, ~VT],Iterable
[Dict
[~KT, ~VT]],None
]) – theEnactment
s specifically cited as failing to preclude application of theprocedure
.mandatory (
bool
) – whether theprocedure
is mandatory for the court to apply whenever theRule
is properly invoked.False
means that theprocedure
is “discretionary”.universal (
bool
) –True
if theprocedure
is applicable whenever its inputs are present.False
means that theprocedure
is applicable in “some” situation where the inputs are present.generic (
bool
) – whether theRule
is being mentioned in a generic context. e.g., if theRule
is being mentioned in anArgument
object merely as an example of the kind ofRule
that might be mentioned in such anArgument
.name – an identifier used to retrieve the
Rule
when needed for the composition of anotherFactor
object.rule_valid (
bool
) – Whether theRule
is asserted to be valid (or useable by a court in litigation).decided (
bool
) – Whether it should be deemed decided whether theRule
is valid. If not, theHolding
have the effect of overruling priorHolding
s finding theRule
to be either valid or invalid.anchors (
Union
[str
,Dict
[~KT, ~VT],Iterable
[Union
[str
,Dict
[~KT, ~VT]]],None
]) – Text selectors for the wholeHolding
, not for any individualFactor
. Often selects text used to indicate whether theRule
ismandatory
,universal
,valid
, ordecided
, or shows theexclusive
way to reach the outputs.mentioned (
Optional
[Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]) – KnownFactor
s that may be reused in constructing the newHolding
.regime (
Optional
[Regime
]) – Collection ofJurisdiction
s and correspondingCode
s for discoveringEnactment
s to reference in the newHolding
.
- Return type
Iterator
[Union
[Holding
,Tuple
[Holding
,Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]]]- Returns
New
Holding
, and an updated dictionary with mentionedFactor
s as keys and theirTextQuoteSelector
s as values.
Load a list of
Holdings
s from JSON, with optional text links.- Parameters
holdings (
Dict
[str
,Iterable
[+T_co]]) – the record from JSON in the format that listsmentioned_factors
followed by a list of holdingsmentioned (
Optional
[Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]) – A dict ofFactor
s that the method needs to expect to find in theHolding
s, linked to lists ofTextQuoteSelector
s indicating where eachFactor
can be found in theOpinion
.
- Parame regime
A collection of
Jurisdiction
s and theCode
s that have been enacted in each. Used for constructingEnactment
s referenced byHolding
s.- Return type
Union
[List
[Holding
],Tuple
[List
[Holding
],Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]]- Returns
a list of
Holding
objects, optionally with an index matchingFactor
s to selectors.
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 singleOpinion
object, otherwise returns an iterator that yields everyOpinion
in the case.as_generator (
bool
) – if True, returns a generator that yields all opinions meeting the query.
- Return type
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
Opinion
s.Typically one record will contain all the
Opinion
s 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 publishedOpinion
s, the CAP API will divide thoseOpinion
s into a separate record for each appeal.The lead opinion is commonly, but not always, the only
Opinion
that creates binding legal authority. Usually everyRule
posited by the leadOpinion
is binding, but some may not be, often because parts of theOpinion
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 thefull_case
flag was used in the API request.decision_date (
str
) – The day theOpinion
s were issued, in ISO format.court (
Dict
[str
,Union
[str
,int
]]) – A dict containing theCourt
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 theOpinion
s 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 theOpinion
s for this decision can be found.lead_only (
bool
) – IfTrue
, returns a singleOpinion
object from the first opinion found in thecasebody/data/opinions
section of the dict, which should usually be the lead opinion. IfFalse
, returns an iterator that yieldsOpinion
objects from every opinion in the case.
- Return type
Make
Rule
from adict
of strings and a list of mentionedFactor
s.- Parameters
inputs (
Union
[str
,Dict
[~KT, ~VT],List
[Union
[str
,Dict
[~KT, ~VT]]],None
]) – data for constructingFactor
inputs for aRule
despite (
Union
[str
,Dict
[~KT, ~VT],List
[Union
[str
,Dict
[~KT, ~VT]]],None
]) – data for constructing despiteFactor
s for aRule
outputs (
Union
[str
,Dict
[~KT, ~VT],List
[Union
[str
,Dict
[~KT, ~VT]]],None
]) – data for constructingFactor
outputs for aRule
enactments (
Union
[Dict
[~KT, ~VT],Iterable
[Dict
[~KT, ~VT]],None
]) – theEnactment
s cited as authority for invoking theprocedure
.enactments_despite (
Union
[Dict
[~KT, ~VT],Iterable
[Dict
[~KT, ~VT]],None
]) – theEnactment
s specifically cited as failing to preclude application of theprocedure
.mandatory (
bool
) – whether theprocedure
is mandatory for the court to apply whenever theRule
is properly invoked.False
means that theprocedure
is “discretionary”.universal (
bool
) –True
if theprocedure
is applicable whenever its inputs are present.False
means that theprocedure
is applicable in “some” situation where the inputs are present.generic (
bool
) – whether theRule
is being mentioned in a generic context. e.g., if theRule
is being mentioned in anArgument
object merely as an example of the kind ofRule
that might be mentioned in such anArgument
.mentioned (
Optional
[Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]) – a series of context factors, including any genericFactor
s that need to be mentioned inPredicate
s. These will have been constructed from thementioned_entities
section of the input JSON.
- Return type
Union
[Rule
,Tuple
[Rule
,Dict
[Union
[Factor
,Enactment
],List
[TextQuoteSelector
]]]]- Returns
iterator yielding
Rule
s with the items frommentioned_entities
ascontext_factors