class_docstr: Stream a collection of US Supreme Court decisions from a compressed json file on disk,
  either as texts or text + metadata pairs.
  
  Download the data (one time only!) from the textacy-data repo
  (https://github.com/bdewilde/textacy-data), and save its contents to disk::
  
      >>> import textacy.datasets
      >>> ds = textacy.datasets.SupremeCourt()
      >>> ds.download()
      >>> ds.info
      {'name': 'supreme_court',
       'site_url': 'http://caselaw.findlaw.com/court/us-supreme-court',
       'description': 'Collection of ~8.4k decisions issued by the U.S. Supreme Court between November 1946 and June 2016.'}
  
  Iterate over decisions as texts or records with both text and metadata::
  
      >>> for text in ds.texts(limit=3):
      ...     print(text[:500], end="\n\n")
      >>> for text, meta in ds.records(limit=3):
      ...     print("\n{} ({})\n{}".format(meta["case_name"], meta["decision_date"], text[:500]))
  
  Filter decisions by a variety of metadata fields and text length::
  
      >>> for text, meta in ds.records(opinion_author=109, limit=3):  # Notorious RBG!
      ...     print(meta["case_name"], meta["decision_direction"], meta["n_maj_votes"])
      >>> for text, meta in ds.records(decision_direction="liberal",
      ...                              issue_area={1, 9, 10}, limit=3):
      ...     print(meta["case_name"], meta["maj_opinion_author"], meta["n_maj_votes"])
      >>> for text, meta in ds.records(opinion_author=102, date_range=('1985-02-11', '1986-02-11')):
      ...     print("\n{} ({})".format(meta["case_name"], meta["decision_date"]))
      ...     print(ds.issue_codes[meta["issue"]], "=>", meta["decision_direction"])
      >>> for text in ds.texts(min_len=250000):
      ...     print(len(text))
  
  Stream decisions into a :class:`textacy.Corpus <textacy.corpus.Corpus>`::
  
      >>> textacy.Corpus("en", data=ds.records(limit=25))
      Corpus(25 docs; 136696 tokens)
  
  Args:
      data_dir (str or :class:`pathlib.Path`): Path to directory on disk
          under which the data is stored, i.e. ``/path/to/data_dir/supreme_court``.
  
  Attributes:
      full_date_range: First and last dates for which decisions are available,
          each as an ISO-formatted string (YYYY-MM-DD).
      decision_directions: All distinct decision directions, e.g. "liberal".
      opinion_author_codes: Mapping of majority opinion authors,
          from id code to full name.
      issue_area_codes: Mapping of high-level issue area of the case's core disagreement,
          from id code to description.
      issue_codes: Mapping of the specific issue of the case's core disagreement,
          from id code to description.
class_docstr_tok: ["Stream","a","collection","of","US","Supreme","Court","decisions","from","a","compressed","json","file","on","disk",",","either","as","texts","or","text","+","metadata","pairs",".","Download","the","data","(","one","time","only","!",")","from","the","textacy-data","repo","(","https",":","\/\/github.com\/bdewilde\/textacy-data",")",",","and","save","its","contents","to","disk",":",":",">",">",">","import","textacy.datasets",">",">",">","ds","=","textacy.datasets.SupremeCourt","(",")",">",">",">","ds.download","(",")",">",">",">","ds.info","{","'name","'",":","'supreme_court","'",",","'site_url","'",":","'http",":","\/\/caselaw.findlaw.com\/court\/us-supreme-court","'",",","'description","'",":","'Collection","of","~8.4k","decisions","issued","by","the","U.S.","Supreme","Court","between","November","1946","and","June","2016",".","'","}","Iterate","over","decisions","as","texts","or","records","with","both","text","and","metadata",":",":",">",">",">","for","text","in","ds.texts","(","limit=3",")",":","...","print","(","text","[",":500","]",",","end=","''","\\n\\n","''",")",">",">",">","for","text",",","meta","in","ds.records","(","limit=3",")",":","...","print","(","``","\\n","{","}","(","{","}",")","\\n","{","}","''",".format","(","meta","[","``","case_name","''","]",",","meta","[","``","decision_date","''","]",",","text","[",":500","]",")",")","Filter","decisions","by","a","variety","of","metadata","fields","and","text","length",":",":",">",">",">","for","text",",","meta","in","ds.records","(","opinion_author=109",",","limit=3",")",":","#","Notorious","RBG","!","...","print","(","meta","[","``","case_name","''","]",",","meta","[","``","decision_direction","''","]",",","meta","[","``","n_maj_votes","''","]",")",">",">",">","for","text",",","meta","in","ds.records","(","decision_direction=","''","liberal","''",",","...","issue_area=","{","1",",","9",",","10","}",",","limit=3",")",":","...","print","(","meta","[","``","case_name","''","]",",","meta","[","``","maj_opinion_author","''","]",",","meta","[","``","n_maj_votes","''","]",")",">",">",">","for","text",",","meta","in","ds.records","(","opinion_author=102",",","date_range=","(","'1985-02-11","'",",","'1986-02-11","'",")",")",":","...","print","(","``","\\n","{","}","(","{","}",")","''",".format","(","meta","[","``","case_name","''","]",",","meta","[","``","decision_date","''","]",")",")","...","print","(","ds.issue_codes","[","meta","[","``","issue","''","]","]",",","``","=",">","''",",","meta","[","``","decision_direction","''","]",")",">",">",">","for","text","in","ds.texts","(","min_len=250000",")",":","...","print","(","len","(","text",")",")","Stream","decisions","into","a",":","class",":","`","textacy.Corpus","<","textacy.corpus.Corpus",">","`",":",":",">",">",">","textacy.Corpus","(","``","en","''",",","data=ds.records","(","limit=25",")",")","Corpus","(","25","docs",";","136696","tokens",")","Args",":","data_dir","(","str","or",":","class",":","`","pathlib.Path","`",")",":","Path","to","directory","on","disk","under","which","the","data","is","stored",",","i.e",".","``","\/path\/to\/data_dir\/supreme_court","``",".","Attributes",":","full_date_range",":","First","and","last","dates","for","which","decisions","are","available",",","each","as","an","ISO-formatted","string","(","YYYY-MM-DD",")",".","decision_directions",":","All","distinct","decision","directions",",","e.g",".","``","liberal","''",".","opinion_author_codes",":","Mapping","of","majority","opinion","authors",",","from","id","code","to","full","name",".","issue_area_codes",":","Mapping","of","high-level","issue","area","of","the","case","'s","core","disagreement",",","from","id","code","to","description",".","issue_codes",":","Mapping","of","the","specific","issue","of","the","case","'s","core","disagreement",",","from","id","code","to","description","."]
docstr: Iterate over decisions in this dataset, optionally filtering by a variety
  of metadata and/or text length, and yield text + metadata pairs,
  in chronological order by decision date.
  
  Args:
      opinion_author: Filter decisions by the name(s) of the majority opinion's author,
          coded as an integer whose mapping is given in
          :attr:`SupremeCourt.opinion_author_codes`.
      decision_direction: Filter decisions by the ideological direction
          of the majority's decision; see
          :attr:`SupremeCourt.decision_directions`.
      issue_area: Filter decisions by the issue area of the case's subject matter,
          coded as an integer whose mapping is given in
          :attr:`SupremeCourt.issue_area_codes`.
      date_range: Filter decisions by the date on which they were decided;
          both start and end date must be specified, but a null value for either
          will be replaced by the min/max date available for the dataset.
      min_len: Filter decisions by the length (# characters) of their text content.
      limit: Yield no more than ``limit`` decisions that match all specified filters.
  
  Yields:
      Text of the next decision in dataset passing all filters,
      and its corresponding metadata.
  
  Raises:
      ValueError: If any filtering options are invalid.
docstr_tok: ["Iterate","over","decisions","in","this","dataset",",","optionally","filtering","by","a","variety","of","metadata","and\/or","text","length",",","and","yield","text","+","metadata","pairs",",","in","chronological","order","by","decision","date",".","Args",":","opinion_author",":","Filter","decisions","by","the","name","(","s",")","of","the","majority","opinion","'s","author",",","coded","as","an","integer","whose","mapping","is","given","in",":","attr",":","`","SupremeCourt.opinion_author_codes","`",".","decision_direction",":","Filter","decisions","by","the","ideological","direction","of","the","majority","'s","decision",";","see",":","attr",":","`","SupremeCourt.decision_directions","`",".","issue_area",":","Filter","decisions","by","the","issue","area","of","the","case","'s","subject","matter",",","coded","as","an","integer","whose","mapping","is","given","in",":","attr",":","`","SupremeCourt.issue_area_codes","`",".","date_range",":","Filter","decisions","by","the","date","on","which","they","were","decided",";","both","start","and","end","date","must","be","specified",",","but","a","null","value","for","either","will","be","replaced","by","the","min\/max","date","available","for","the","dataset",".","min_len",":","Filter","decisions","by","the","length","(","#","characters",")","of","their","text","content",".","limit",":","Yield","no","more","than","``","limit","``","decisions","that","match","all","specified","filters",".","Yields",":","Text","of","the","next","decision","in","dataset","passing","all","filters",",","and","its","corresponding","metadata",".","Raises",":","ValueError",":","If","any","filtering","options","are","invalid","."]
code: def records(
      self,
      *,
      opinion_author: Optional[int | set[int]] = None,
      decision_direction: Optional[str | set[str]] = None,
      issue_area: Optional[int | set[int]] = None,
      date_range: Optional[tuple[Optional[str], Optional[str]]] = None,
      min_len: Optional[int] = None,
      limit: Optional[int] = None,
  ) -> Iterable[types.Record]:
      """
      Iterate over decisions in this dataset, optionally filtering by a variety
      of metadata and/or text length, and yield text + metadata pairs,
      in chronological order by decision date.
  
      Args:
          opinion_author: Filter decisions by the name(s) of the majority opinion's author,
              coded as an integer whose mapping is given in
              :attr:`SupremeCourt.opinion_author_codes`.
          decision_direction: Filter decisions by the ideological direction
              of the majority's decision; see
              :attr:`SupremeCourt.decision_directions`.
          issue_area: Filter decisions by the issue area of the case's subject matter,
              coded as an integer whose mapping is given in
              :attr:`SupremeCourt.issue_area_codes`.
          date_range: Filter decisions by the date on which they were decided;
              both start and end date must be specified, but a null value for either
              will be replaced by the min/max date available for the dataset.
          min_len: Filter decisions by the length (# characters) of their text content.
          limit: Yield no more than ``limit`` decisions that match all specified filters.
  
      Yields:
          Text of the next decision in dataset passing all filters,
          and its corresponding metadata.
  
      Raises:
          ValueError: If any filtering options are invalid.
      """
      filters = self._get_filters(
          opinion_author,
          decision_direction,
          issue_area,
          date_range,
          min_len,
      )
      for record in itertools.islice(
          self._filtered_iter(filters), limit
      ):
          yield types.Record(text=record.pop("text"), meta=record)
  
file_path: textacy/src/textacy/datasets/supreme_court.py
imports: from __future__ import annotations
  import itertools
  import logging
  import urllib.parse
  from typing import ClassVar, Dict, Iterable, Optional
  from ..None import constants
  from ..None import io
  from ..None import types, utils
  from .base import Dataset
label_desc: Use image node_id 8 for calling the SupremeCourt obj's underlying member method code with example usage: obj.records() without return types