OSCN utilities

A python library for scraping case information from the Oklahoma State Courts Network.

Update:

04/2025: Completed migration to Selectolax. BeautifulSoup has been removed as a dependency. All parsers now use Selectolax.
12/16/2024: Updated to use Selectolax instead of BeautifulSoup. Most parsing functions now use Selectolax which is faster and more memory efficient.

oscn > Python package source to provide an api for retrieving and parsing case records.

scripts > Python scripts showing use of the oscn package

example.py: demonstrates use of the request Case and Caselist
retrieve-counts.py: saves a list of all counts for a list of counties and years
find-counts.py: saves a list of counts passing a test for a list of counties and years
soup_test.py: a stub for testing parsing attempts using BeautifulSoup
parse_test.py: a stub for developing using saved examples

OSCN package

oscn

counties: Returns a list of counties.
courts: Same as counties but more a accurate description.
judges: Returns a list of objects formated as {'name': 'Bond, James', 'number': '007'}
types: returns a dict of case type codes and descriptons
type: function to return case type description. Usage:
```
>>> oscn.type("AO")
'CIVIL ADMINISTRATIVE'
```

oscn.request

Case: Returns a single case. Case can be saved as files using Case.save() and retrieved using Case.open().
CaseList: Returns an iterator for retrieving cases for a county and year. CaseLists can be filtered using .find(). See scripts/example.py for details
Party: Returns information on parties available on OSCN.
Docket: Returns docket of cases for specific judges and date

oscn.parse

Parsers accept the html of an OSCN page and return python objects.

Case Page Parsers

filed: returns a string of the filing date (e.g. 12/25/2017)
closed: returns a string of the date the case was closed. Return None if not closed.
counts: returns of list of count dicts found in a case. Keys include 'description' of the count. If available 'violation' and 'disposed' are added.
judge: returns a string of the judge's name
parties: returns a list of dicts with these keys: id, name, type
docket: returns a list of rows in a docket
events: returns a list of dicts with these keys: event, party, docket, reporter, date, description. The keys date and description are cleaner versions of the event text. The event key will be deprecated some day so use date and description if you are starting a project.
attorneys: returns a list of dicts with these keys: name, address, and representing
issues: returns a list of dicts with issue information. Each issues includes a list of dicts for each party

Party Page Parsers

name: returns 'Requested Party'
alias: returns 'Alias or Alternate Names'
profile: returns dict of values in 'Personal Profile'
birth_month: returns string of 'Birth Month and Year'
addresses: returns a list of dicts for each address

Docket Page Parsers

cases: returns a list of case indexes
tables: returns the html table for each case in the docket

oscn.find

CaseIndexes: returns an iterator of case indexes (e.g. tulsa-CF-2019-12).

Usage

Create a CaseIndexes list using these key word arguments:

county: defaults to all,
last_name: use this for company or organization names
first_name: optional
middle_name: optional
filed_after: More readable than FiledDateL
filed_before: More readable than FiledDateH
closed_after: More readable than ClosedDateL
closed_before: More readable than ClosedDateH

Notes

The % wild card is added to all words in name, first and middle
Date arguments use MM/DD/YYY strings.

OSCN search parameters

If you are familar with the OSCN search parameters you can initialize CaseIndexes using these as key word arguments: db, number, lname, fname, mname, DoBMin, DoBMax, partytype, apct, dcct, FiledDate, FiledDateH, ClosedDateL, ClosedDateH, iLC, iLCType, iYear, iNumber, and citation

Using this will override init keyword values such as first or filed_after.

Installation

To install the latest version of this package, run the following command: pip install oscn

For development, clone the repository and install the dependencies using poetry: git clone git@github.com:codefortulsa/oscn.git cd oscn poetry install

Usage

Script example:

import oscn

Request a single case:

oscn.request.Case(county='tulsa', year='2018', number=84)

or use case index notation:

oscn.request.Case('love-CF-2019-25')

To request a list of cases to iterate:

oscn.request.CaseList(county='adair', year='2016')

Run test scripts

poetry run pytest tests/

or with ipdb:

- `poetry run pytest -s tests/`

specify a test:

poetry run pytest -s tests/test_parse.py -k 'test_events'

parallel testing: -poetry run pytest -n auto

Deployment steps

To deploy a new version of the package, follow these steps:

poetry version patch
poetry build
poetry publish

User Agent

In some cases a custom user agent is required in the header of requests. Setting an environmental varialbe called OSCN_USER_AGENT will override the default.

This project is open-source and contributions are welcome.

Release Notes

Version 0.0.98

Completed full migration from BeautifulSoup to Selectolax. All parsers (parties, attorneys, counts, issues, events, docket, cmids, party_addresses, party_profile, party_properties, docket_report, find/parse) now use Selectolax exclusively.
Removed beautifulsoup4 as a dependency.
Removed global SSL warning suppression that was masking urllib3 warnings.

Version 0.0.92

Added the .documents property to the Case object, which parses the case docket and returns a list of all linked documents. Each document is a dictionary with the following structure:

{
  "id": 1234567,
  "title": "MOTION TO COMPEL",
  "url": "https://www.oscn.net/dockets/GetDocument.aspx?...",
  "date": "01-01-2024",
  "code": "MO",
  "party": "PLAINTIFF"
}

Metadata

Release files for oscn 0.0.99

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oscn 0.0.99
File	Size	Uploaded	Provenance
oscn-0.0.99.tar.gz	30.9 kB	Jun 18, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for oscn 0.0.99
File	Interpreter	ABI	Platform	Reset
oscn-0.0.99-py3-none-any.whl 37.2 kB Jun 18, 2026 Without provenance	Python 3	none	any	Details

Total release size: 68.1 kB

Release files / oscn-0.0.99.tar.gz

Download URL	oscn-0.0.99.tar.gz
Size	30.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`ca8242f79082bf3a298997b4b93028cb11c0643c41172f5b8c5ed4acf4ce4125`
BLAKE2b-256 checksum How to use checksums	`9afa4229d9bd47082e6514edd6e870d8960ffb80afc5b068d9d30c6ce69c4b13`
Upload date	Jun 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.3 CPython/3.11.12 Darwin/25.5.0`

Release files / oscn-0.0.99-py3-none-any.whl

Download URL	oscn-0.0.99-py3-none-any.whl
Size	37.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`96193a08d68deec4052e0f56e37563d0160cc33acef7424b76417877da0e5d04`
BLAKE2b-256 checksum How to use checksums	`638fd3ffe3d6b200ff6d2119b0862f8204b8c990a02773897fdbd8eab116ff08`
Upload date	Jun 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.3 CPython/3.11.12 Darwin/25.5.0`

Security for oscn 0.0.99

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.