Skip to content

Commit 832f9d5

Browse files
duckduckgrayduckduckduckgrayduck
committed
First round of documentation
1 parent c7d19a5 commit 832f9d5

File tree

8 files changed

+499
-1
lines changed

8 files changed

+499
-1
lines changed

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
11
# python-muckrock
2-
A Python wrapper for the MuckRock API, allowing for users to search and file requests and search other endpoints.
2+
A Python wrapper for the MuckRock API, allowing for users to search and file requests and search other endpoints.
3+
4+
Issues: https://github.com/MuckRock/python-muckrock/issues

‎docs/agencies.rst‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
Agencies
2+
===========
3+
4+
Methods for searching and retrieving agencies.
5+
6+
AgencyClient
7+
----------------
8+
9+
.. class:: muckrock.agencies.AgencyClient
10+
The agency client allows access to search and retrieval of agencies via the MuckRock API. The client supports querying, listing, and retrieving specific agencies.
11+
12+
.. method:: list(self, **params)
13+
List all agencies with optional filtering by parameters. Filters include:
14+
- **name**: The agency name. Partial matches are supported.
15+
- **jurisdiction**: the ID of the Jurisidiction the agency belongs to.
16+
:param params: Query parameters to filter results (e.g., `jurisdiction`, `name`).
17+
:return: An :class:`APIResults` object containing the list of agencies.
18+
19+
.. method:: retrieve(self, agency_id)
20+
Retrieve a specific agency by its unique identifier.
21+
:param agency_id: The unique ID of the agency to retrieve.
22+
:return: An :class:`Agency` object representing the requested agency.
23+
24+
25+
Agency
26+
----------------
27+
.. class:: muckrock.agencies.Agency
28+
29+
A representation of a single agency.
30+
31+
.. method:: str()
32+
Returns a string representation of the agency, which is the `name` of the agency.
33+
34+
.. attribute:: id
35+
The unique identifier for the agency.
36+
37+
.. attribute:: name
38+
The name of the agency.
39+
40+
.. attribute:: slug
41+
The slug (URL identifier) for the agency.
42+
43+
.. attribute:: status
44+
The current operational status of the agency (e.g., pending, approved, rejected).
45+
46+
.. attribute:: exempt
47+
Indicates whether the agency is exempt from records laws
48+
49+
.. attribute:: types
50+
A list of types of agency (e.g., Police, Transportation, Military).
51+
52+
.. attribute:: requires_proxy
53+
Indicates whether the agency requires a proxy because of in-state residency laws.
54+
55+
.. attribute:: jurisdiction
56+
The jurisdiction to which the agency belongs.
57+
58+
.. attribute:: parent
59+
The ID of the parent agency
60+
61+
.. attribute:: appeal_agency
62+
The ID of the agency to which appeals are directed

‎docs/communications.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Communications
2+
===========
3+
4+
Methods for searching and retrieving FOIA communications.
5+
6+
CommunicationClient
7+
----------------
8+
.. class:: documentcloud.communications.CommunicationClient
9+
10+
The communication client allows access to search, list, and retrieve individual FOIA communications.
11+
12+
.. method:: list(self, **params)
13+
List all FOIA communications with optional filtering. Available filters include:
14+
15+
- **max_date**: Filter communications before a specific date. Format: YYYY-MM-DD
16+
- **min_date**: Filter communications after a specific date. Format: YYYY-MM-DD
17+
- **foia**: Filter by the associated FOIA request's ID.
18+
- **status**: Filter by the status of the communication (e.g., `submitted`, `ack`, `processed`, etc.).
19+
- **response**: Filter communications based on whether they are a response (boolean).
20+
21+
:param params: Query parameters to filter results (e.g., `foia`, `max_date`, `response`).
22+
:return: An :class:`APIResults` object containing the list of communications.
23+
24+
.. method:: retrieve(self, communication_id)
25+
Retrieve a specific FOIA communication by its unique identifier.
26+
27+
:param communication_id: The unique ID of the communication to retrieve.
28+
:return: A :class:`Communication` object representing the requested communication.
29+
30+
Communication
31+
----------------
32+
.. class:: documentcloud.communications.Communication
33+
34+
A representation of a single FOIA communication.
35+
36+
.. method:: str()
37+
Returns a string representation of the communication in the format: `Communication {id}`.
38+
39+
.. attribute:: id
40+
The unique identifier for the communication.
41+
42+
.. attribute:: foia
43+
The ID of the associated FOIA request.
44+
45+
.. attribute:: from_user
46+
The ID of the user sending this communication.
47+
48+
.. attribute:: to_user
49+
The ID of the user receiving this communication.
50+
51+
.. attribute:: subject
52+
The subject of the communication, up to 255 characters.
53+
54+
.. attribute:: datetime
55+
The date and time when the communication was sent.
56+
57+
.. attribute:: response
58+
A boolean indicating if the communication is a response.
59+
60+
.. attribute:: autogenerated
61+
A boolean indicating if the communication was autogenerated.
62+
63+
.. attribute:: communication
64+
The content or text of the communication.
65+
66+
.. attribute:: status
67+
The status of the communication, such as `submitted`, `ack`, `processed`, `done`, etc.
68+
69+
.. attribute:: files
70+
A list of integers representing the file IDs associated with this communication.

‎docs/files.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
Files
2+
===========
3+
4+
Methods for searching and retrieving files attached to FOIA communications.
5+
6+
FileClient
7+
----------------
8+
.. class:: documentcloud.files.FileClient
9+
10+
The file client allows access to search, list, and retrieve individual FOIA files.
11+
12+
.. method:: list(self, **params)
13+
List all FOIA files with optional filtering. Available filters include:
14+
15+
- **communication**: Filter by the associated communication's ID.
16+
- **title**: Filter by the file title.
17+
- **doc_id**: Filter by unique identifier for the document (different than the ID of the file).
18+
19+
:param params: Query parameters to filter results, such as `communication`, `title`, and `doc_id`.
20+
:return: An :class:`APIResults` object containing the list of files.
21+
22+
.. method:: retrieve(self, file_id)
23+
24+
Retrieve a specific FOIA file by its unique identifier.
25+
26+
:param file_id: The unique ID of the file to retrieve.
27+
:return: A :class:`File` object representing the requested file.
28+
29+
File
30+
----------------
31+
.. class:: documentcloud.files.File
32+
33+
A representation of a single FOIA file.
34+
35+
.. method:: str()
36+
Returns a string representation of the file in the format: `File {id} - Title: {title}`.
37+
38+
.. attribute:: id
39+
The unique identifier for the file.
40+
41+
.. attribute:: ffile
42+
The URL of the file.
43+
44+
.. attribute:: datetime
45+
The date and time when the file was uploaded.
46+
47+
.. attribute:: title
48+
The title of the file.
49+
50+
.. attribute:: source
51+
The source of the file (e.g., the agency or department).
52+
53+
.. attribute:: description
54+
A description of the file.
55+
56+
.. attribute:: doc_id
57+
Filter by the document identifier assigned to the file.
58+
59+
.. attribute:: pages
60+
The number of pages in the file.

‎docs/jurisdictions.rst‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
Jurisdictions
2+
===========
3+
4+
Methods for searching and retrieving jurisdictions.
5+
6+
JurisdictionClient
7+
----------------
8+
.. class:: documentcloud.jurisdictions.JurisdictionClient
9+
10+
The jurisdiction client allows access to search, list, and retrieve individual jurisdictions.
11+
12+
.. method:: list(self, **params)
13+
List all jurisdictions with optional filtering. Available filters include:
14+
15+
- **abbrev**: Filter by the jurisdiction abbreviation. Local jurisdictions typically don't have an abbreviation.
16+
- **level**: Filter by the level of the jurisdiction (e.g., `f` for Federal, `s` for State, `l` for Local).
17+
- **name**: Filter by the jurisdiction's name.
18+
- **parent**: Filter by the ID of the parent jurisdiction. Jurisdictions can have a federal or state parent, while local jurisdictions cannot be parents.
19+
20+
:param params: Query parameters to filter results, such as `abbrev`, `level`, `name`, and `parent`.
21+
:return: An :class:`APIResults` object containing the list of jurisdictions.
22+
23+
.. method:: retrieve(self, jurisdiction_id)
24+
Retrieve a specific jurisdiction by its unique identifier.
25+
26+
:param jurisdiction_id: The unique ID of the jurisdiction to retrieve.
27+
:return: A :class:`Jurisdiction` object representing the requested jurisdiction.
28+
29+
Jurisdiction
30+
----------------
31+
.. class:: documentcloud.jurisdictions.Jurisdiction
32+
A representation of a jurisdiction.
33+
34+
.. method:: str()
35+
Return a string representation of the jurisdiction - its `name`.
36+
37+
.. attribute:: id
38+
The unique identifier for the jurisdiction.
39+
40+
.. attribute:: name
41+
The name of the jurisdiction.
42+
43+
.. attribute:: slug
44+
The URL-friendly identifier for the jurisdiction.
45+
46+
.. attribute:: abbrev
47+
The abbreviation for the jurisdiction. Local jurisdictions do not have one.
48+
49+
.. attribute:: level
50+
The level of the jurisdiction, which can be:
51+
- `f` for Federal
52+
- `s` for State
53+
- `l` for Local
54+
55+
.. attribute:: parent
56+
The ID of the parent jurisdiction, defining the hierarchy between jurisdictions. A jurisdiction can have a federal or state parent, while local jurisdictions cannot be parents.

‎docs/organizations.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
Organization
2+
===========
3+
4+
Methods for searching and retrieving organizations.
5+
6+
OrganizationClient
7+
----------------
8+
.. class:: documentcloud.organizations.OrganizationClient
9+
10+
The organization client allows access to search, list, and retrieve individual organizations.
11+
12+
.. method:: list(self, **params)
13+
List all organizations with optional filtering. Available filters include:
14+
15+
- **name**: Filter by the organization name.
16+
- **slug**: Filter by the organization's slug (URL identifier).
17+
- **uuid**: Filter by the unique identifier for the organization.
18+
19+
:param params: Query parameters to filter results, such as `name`, `slug`, and `uuid`
20+
:return: An :class:`APIResults` object containing the list of organizations.
21+
22+
.. method:: retrieve(self, organization_id)
23+
Retrieve a specific organization by its ID.
24+
25+
:param organization_id: The unique ID of the organization to retrieve.
26+
:return: An :class:`Organization` object representing the requested organization.
27+
28+
29+
Organization
30+
----------------
31+
.. class:: documentcloud.organizations.Organization
32+
33+
A representation of a single organization.
34+
35+
.. method:: str()
36+
Return a string representation of the organization in the format `Organization {id} - Name: {name}`.
37+
38+
.. attribute:: id
39+
The numerical unique ID of the organization.
40+
41+
.. attribute:: name
42+
The name of the organization.
43+
44+
.. attribute:: slug
45+
The URL-friendly identifier (slug) for the organization.
46+
47+
.. attribute:: uuid
48+
The unique identifier for the organization (UUID format).
49+
50+
.. attribute:: individual
51+
A boolean indicating if the organization is an individual organization or not.
52+
53+
.. attribute:: entitlement
54+
The ID of the entitlements associated with the organization.
55+
56+
.. attribute:: verified_journalist
57+
A boolean indicating if the organization is verified as a journalist. This allows members of this organization to upload documents to DocumentCloud among other things.
58+
59+
.. attribute:: users
60+
A list of user IDs associated with the organization.

0 commit comments

Comments
 (0)