xbrlkit 0.7.2__tar.gz → 0.7.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/PKG-INFO +62 -10
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/README.md +61 -9
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/pyproject.toml +1 -1
- xbrlkit-0.7.4/tests/conftest.py +25 -0
- xbrlkit-0.7.4/tests/test_config.py +117 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_serialize.py +31 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_serve.py +35 -0
- xbrlkit-0.7.4/xbrlkit/config.py +154 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/deserialize/holon.py +4 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/client.py +1 -1
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/efts.py +1 -1
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/context.py +6 -2
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/graph.py +8 -4
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/server.py +41 -1
- xbrlkit-0.7.2/tests/conftest.py +0 -13
- xbrlkit-0.7.2/tests/test_config.py +0 -51
- xbrlkit-0.7.2/xbrlkit/config.py +0 -68
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/.gitignore +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/LICENSE +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/pytest.ini +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/ruff.toml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_arelle_cache.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_deserialize.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_documents.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_edgar.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_efts.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_lpg.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_oim.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_parity.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_parse.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_query.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_tavi.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_text_ixbrl.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_text_narrative.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_text_parts.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_text_tables.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/README.md +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/extractTestcase.sh +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/extractTestcase.xsl +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/runIxtSecTests.sh +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/saxon9.jar +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/testcase.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/tests.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/tests.xsd +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/text2num.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-boolballotbox.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-countrynameen.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-datequarterend.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durday.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durhour.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durmonth.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durweek.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durwordsen.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-duryear.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-edgarprovcountryen.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-entityfilercategoryen.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-exchnameen.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-numwordsen.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-stateprovnameen.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-yesnoballotbox.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/transform-registry.xml +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/schema/inlinexbrl-sec-transformation.xsd +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/ontology/v1/context.jsonld +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/ontology/v1/shapes.ttl +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/cli.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/deserialize/README.md +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/deserialize/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/deserialize/tavi.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/README.md +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/download.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/filing_index.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/rate_limit.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/submission.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/filings_org/README.md +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/filings_org/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/filings_org/client.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/filings_org/download.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/model.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/namespaces.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/README.md +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/arelle_load.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/cache.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/ids.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/to_model.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/periods.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/py.typed +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/query.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/schema/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/README.md +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/bundle.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/holon.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/jsonld.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_values.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/classify.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/holon.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/lpg.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/oim.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/tavi.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/README.md +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/session.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/tools.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/README.md +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/__init__.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/ixbrl.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/narrative.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/parts.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/tables.py +0 -0
- {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/xml.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: xbrlkit
|
|
3
|
-
Version: 0.7.
|
|
3
|
+
Version: 0.7.4
|
|
4
4
|
Summary: Work with XBRL filings above Arelle: one parse, portable models
|
|
5
5
|
Project-URL: Repository, https://github.com/RoboFinSystems/xbrlkit
|
|
6
6
|
Project-URL: Homepage, https://github.com/RoboFinSystems/xbrlkit#readme
|
|
@@ -125,19 +125,29 @@ just install # dependencies, and .env from the template
|
|
|
125
125
|
|
|
126
126
|
### SEC User-Agent
|
|
127
127
|
|
|
128
|
-
SEC
|
|
129
|
-
|
|
130
|
-
|
|
128
|
+
SEC fair access asks for a `User-Agent` identifying you with contact info.
|
|
129
|
+
EDGAR works out of the box under a default that names the project, and the
|
|
130
|
+
first unattributed fetch says so once — SEC rate limits per IP, so the shared
|
|
131
|
+
default costs nobody else their budget. Identifying yourself is a courtesy,
|
|
132
|
+
and one worth extending. `just install` already created your `.env`:
|
|
131
133
|
|
|
132
134
|
```bash
|
|
133
135
|
# .env
|
|
134
136
|
SEC_GOV_USER_AGENT="Your Name your@email.com"
|
|
135
137
|
```
|
|
136
138
|
|
|
137
|
-
`.env` is loaded automatically by every command
|
|
138
|
-
|
|
139
|
+
`.env` is loaded automatically by every command **run from a checkout of this
|
|
140
|
+
repo** — the lookup is relative to the installed code, not your working
|
|
141
|
+
directory, so a `uvx` or `pip` install never picks one up. There, use
|
|
142
|
+
`export SEC_GOV_USER_AGENT=…`, `--user-agent`, or an MCP `env` block (see
|
|
143
|
+
[Serve to an MCP client](#serve-to-an-mcp-client)). Nothing outside EDGAR
|
|
139
144
|
needs it — a local file, a JSON report and filings.xbrl.org all load without.
|
|
140
145
|
|
|
146
|
+
> **Do not put a GitHub URL in it.** EDGAR answers `403` to any `User-Agent`
|
|
147
|
+
> containing `github.com`, whatever else the header says, and the failure
|
|
148
|
+
> looks like a permissions problem rather than a header problem. A name and
|
|
149
|
+
> an email is the shape that works.
|
|
150
|
+
|
|
141
151
|
## Usage
|
|
142
152
|
|
|
143
153
|
```bash
|
|
@@ -172,20 +182,62 @@ model = from_holon_json(holon) # and back again
|
|
|
172
182
|
|
|
173
183
|
## Serve to an MCP client
|
|
174
184
|
|
|
185
|
+
Two ways to run it. They differ in which process does the fetching, and so in
|
|
186
|
+
where your SEC identity goes.
|
|
187
|
+
|
|
188
|
+
**stdio — the client launches the server.** The identity belongs in the
|
|
189
|
+
server's own `env` block:
|
|
190
|
+
|
|
191
|
+
```json
|
|
192
|
+
{
|
|
193
|
+
"mcpServers": {
|
|
194
|
+
"xbrlkit": {
|
|
195
|
+
"command": "uvx",
|
|
196
|
+
"args": [
|
|
197
|
+
"--from", "xbrlkit[mcp]@latest",
|
|
198
|
+
"xbrlkit", "serve", "--transport", "stdio"
|
|
199
|
+
],
|
|
200
|
+
"env": { "SEC_GOV_USER_AGENT": "Your Name you@example.com" }
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
**HTTP — you start the server, the client only points at a URL.** An `env`
|
|
207
|
+
block in the client config would reach nothing here; set it on the command:
|
|
208
|
+
|
|
175
209
|
```bash
|
|
176
210
|
pip install "xbrlkit[mcp]"
|
|
177
|
-
xbrlkit serve
|
|
211
|
+
SEC_GOV_USER_AGENT="Your Name you@example.com" xbrlkit serve
|
|
178
212
|
# → MCP at http://127.0.0.1:8765/mcp
|
|
179
213
|
|
|
180
|
-
|
|
214
|
+
# or without installing anything
|
|
215
|
+
SEC_GOV_USER_AGENT="Your Name you@example.com" \
|
|
216
|
+
uvx --from "xbrlkit[mcp]@latest" xbrlkit serve
|
|
181
217
|
```
|
|
182
218
|
|
|
183
|
-
|
|
219
|
+
```json
|
|
220
|
+
{
|
|
221
|
+
"mcpServers": {
|
|
222
|
+
"xbrlkit": { "type": "http", "url": "http://127.0.0.1:8765/mcp" }
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
or, equivalently:
|
|
184
228
|
|
|
185
229
|
```bash
|
|
186
|
-
|
|
230
|
+
claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp
|
|
187
231
|
```
|
|
188
232
|
|
|
233
|
+
A `.env` file is **not** a channel for either of these. The lookup is relative
|
|
234
|
+
to the installed code rather than your working directory, so it resolves only
|
|
235
|
+
inside a checkout of this repo — a `uvx` or `pip` install never sees one. Use
|
|
236
|
+
the environment, the `env` block, or `--user-agent`.
|
|
237
|
+
|
|
238
|
+
Both are optional: EDGAR works unattributed under the default, saying so once.
|
|
239
|
+
And filings.xbrl.org, local packages and Tavi/holon JSON need no identity at all.
|
|
240
|
+
|
|
189
241
|
Then load filings from the chat — a ticker, an EDGAR `cik:accession`, a
|
|
190
242
|
`lei:`, a local package, or a holon or Tavi by path or URL — and ask for
|
|
191
243
|
statements, facts by concept and period, calculations, exhibits and text.
|
|
@@ -69,19 +69,29 @@ just install # dependencies, and .env from the template
|
|
|
69
69
|
|
|
70
70
|
### SEC User-Agent
|
|
71
71
|
|
|
72
|
-
SEC
|
|
73
|
-
|
|
74
|
-
|
|
72
|
+
SEC fair access asks for a `User-Agent` identifying you with contact info.
|
|
73
|
+
EDGAR works out of the box under a default that names the project, and the
|
|
74
|
+
first unattributed fetch says so once — SEC rate limits per IP, so the shared
|
|
75
|
+
default costs nobody else their budget. Identifying yourself is a courtesy,
|
|
76
|
+
and one worth extending. `just install` already created your `.env`:
|
|
75
77
|
|
|
76
78
|
```bash
|
|
77
79
|
# .env
|
|
78
80
|
SEC_GOV_USER_AGENT="Your Name your@email.com"
|
|
79
81
|
```
|
|
80
82
|
|
|
81
|
-
`.env` is loaded automatically by every command
|
|
82
|
-
|
|
83
|
+
`.env` is loaded automatically by every command **run from a checkout of this
|
|
84
|
+
repo** — the lookup is relative to the installed code, not your working
|
|
85
|
+
directory, so a `uvx` or `pip` install never picks one up. There, use
|
|
86
|
+
`export SEC_GOV_USER_AGENT=…`, `--user-agent`, or an MCP `env` block (see
|
|
87
|
+
[Serve to an MCP client](#serve-to-an-mcp-client)). Nothing outside EDGAR
|
|
83
88
|
needs it — a local file, a JSON report and filings.xbrl.org all load without.
|
|
84
89
|
|
|
90
|
+
> **Do not put a GitHub URL in it.** EDGAR answers `403` to any `User-Agent`
|
|
91
|
+
> containing `github.com`, whatever else the header says, and the failure
|
|
92
|
+
> looks like a permissions problem rather than a header problem. A name and
|
|
93
|
+
> an email is the shape that works.
|
|
94
|
+
|
|
85
95
|
## Usage
|
|
86
96
|
|
|
87
97
|
```bash
|
|
@@ -116,20 +126,62 @@ model = from_holon_json(holon) # and back again
|
|
|
116
126
|
|
|
117
127
|
## Serve to an MCP client
|
|
118
128
|
|
|
129
|
+
Two ways to run it. They differ in which process does the fetching, and so in
|
|
130
|
+
where your SEC identity goes.
|
|
131
|
+
|
|
132
|
+
**stdio — the client launches the server.** The identity belongs in the
|
|
133
|
+
server's own `env` block:
|
|
134
|
+
|
|
135
|
+
```json
|
|
136
|
+
{
|
|
137
|
+
"mcpServers": {
|
|
138
|
+
"xbrlkit": {
|
|
139
|
+
"command": "uvx",
|
|
140
|
+
"args": [
|
|
141
|
+
"--from", "xbrlkit[mcp]@latest",
|
|
142
|
+
"xbrlkit", "serve", "--transport", "stdio"
|
|
143
|
+
],
|
|
144
|
+
"env": { "SEC_GOV_USER_AGENT": "Your Name you@example.com" }
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
**HTTP — you start the server, the client only points at a URL.** An `env`
|
|
151
|
+
block in the client config would reach nothing here; set it on the command:
|
|
152
|
+
|
|
119
153
|
```bash
|
|
120
154
|
pip install "xbrlkit[mcp]"
|
|
121
|
-
xbrlkit serve
|
|
155
|
+
SEC_GOV_USER_AGENT="Your Name you@example.com" xbrlkit serve
|
|
122
156
|
# → MCP at http://127.0.0.1:8765/mcp
|
|
123
157
|
|
|
124
|
-
|
|
158
|
+
# or without installing anything
|
|
159
|
+
SEC_GOV_USER_AGENT="Your Name you@example.com" \
|
|
160
|
+
uvx --from "xbrlkit[mcp]@latest" xbrlkit serve
|
|
125
161
|
```
|
|
126
162
|
|
|
127
|
-
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"mcpServers": {
|
|
166
|
+
"xbrlkit": { "type": "http", "url": "http://127.0.0.1:8765/mcp" }
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
or, equivalently:
|
|
128
172
|
|
|
129
173
|
```bash
|
|
130
|
-
|
|
174
|
+
claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp
|
|
131
175
|
```
|
|
132
176
|
|
|
177
|
+
A `.env` file is **not** a channel for either of these. The lookup is relative
|
|
178
|
+
to the installed code rather than your working directory, so it resolves only
|
|
179
|
+
inside a checkout of this repo — a `uvx` or `pip` install never sees one. Use
|
|
180
|
+
the environment, the `env` block, or `--user-agent`.
|
|
181
|
+
|
|
182
|
+
Both are optional: EDGAR works unattributed under the default, saying so once.
|
|
183
|
+
And filings.xbrl.org, local packages and Tavi/holon JSON need no identity at all.
|
|
184
|
+
|
|
133
185
|
Then load filings from the chat — a ticker, an EDGAR `cik:accession`, a
|
|
134
186
|
`lei:`, a local package, or a holon or Tavi by path or URL — and ask for
|
|
135
187
|
statements, facts by concept and period, calculations, exhibits and text.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""Shared pytest fixtures for the xbrlkit test suite."""
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
|
|
5
|
+
import pytest
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
@pytest.fixture
|
|
9
|
+
def sample_output_dir(tmp_path: Path) -> Path:
|
|
10
|
+
"""Return a temporary directory for tests that write output artifacts."""
|
|
11
|
+
out = tmp_path / "output"
|
|
12
|
+
out.mkdir()
|
|
13
|
+
return out
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@pytest.fixture(autouse=True)
|
|
17
|
+
def declared_sec_identity(monkeypatch):
|
|
18
|
+
"""Give every test a SEC identity of its own.
|
|
19
|
+
|
|
20
|
+
The EDGAR and EFTS clients refuse to start without one. Setting a fixed
|
|
21
|
+
test value here keeps the suite hermetic: it neither depends on the
|
|
22
|
+
developer's ``SEC_GOV_USER_AGENT`` nor sends their address anywhere. Tests
|
|
23
|
+
that exercise the absent case delete it themselves.
|
|
24
|
+
"""
|
|
25
|
+
monkeypatch.setenv("SEC_GOV_USER_AGENT", "xbrlkit tests tests@example.com")
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
"""The SEC User-Agent / ``.env`` config contract.
|
|
2
|
+
|
|
3
|
+
The CLI calls ``load_dotenv()`` at startup and then builds a fresh ``Config``,
|
|
4
|
+
so a ``SEC_GOV_USER_AGENT`` set in a local ``.env`` reaches the EDGAR client.
|
|
5
|
+
These tests exercise that env -> ``Config`` path without any network access.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from dotenv import load_dotenv
|
|
14
|
+
|
|
15
|
+
import pytest
|
|
16
|
+
|
|
17
|
+
import xbrlkit.config as config_module
|
|
18
|
+
from xbrlkit.config import DEFAULT_USER_AGENT, Config
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def test_env_user_agent_overrides_default(monkeypatch):
|
|
22
|
+
monkeypatch.setenv("SEC_GOV_USER_AGENT", "Acme Corp ops@acme.com")
|
|
23
|
+
cfg = Config()
|
|
24
|
+
assert cfg.user_agent == "Acme Corp ops@acme.com"
|
|
25
|
+
assert cfg.headers["User-Agent"] == "Acme Corp ops@acme.com"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def test_no_identity_when_unset(monkeypatch):
|
|
29
|
+
"""Unset means unset — the config never invents an identity."""
|
|
30
|
+
monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
|
|
31
|
+
assert Config().user_agent is None
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def test_generic_headers_name_the_software_not_an_operator(monkeypatch):
|
|
35
|
+
"""Every host gets a default whose address is reserved, so it reaches nobody."""
|
|
36
|
+
monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
|
|
37
|
+
agent = Config().headers["User-Agent"]
|
|
38
|
+
assert agent == DEFAULT_USER_AGENT
|
|
39
|
+
assert agent.endswith("@example.com")
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def test_sec_headers_fall_back_to_the_default(monkeypatch):
|
|
43
|
+
"""EDGAR still works undeclared — the default is a courtesy, not a gate."""
|
|
44
|
+
monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
|
|
45
|
+
monkeypatch.setattr(config_module, "_warned_undeclared", False)
|
|
46
|
+
assert Config().sec_headers == {"User-Agent": DEFAULT_USER_AGENT}
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@pytest.mark.parametrize("blank", ["", " "])
|
|
50
|
+
def test_a_blank_identity_is_no_identity(monkeypatch, blank):
|
|
51
|
+
monkeypatch.setenv("SEC_GOV_USER_AGENT", blank)
|
|
52
|
+
monkeypatch.setattr(config_module, "_warned_undeclared", False)
|
|
53
|
+
assert Config().sec_headers == {"User-Agent": DEFAULT_USER_AGENT}
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def test_undeclared_identity_warns_exactly_once(monkeypatch, caplog):
|
|
57
|
+
"""Behind every EDGAR request, so a repeat per call would be pure noise."""
|
|
58
|
+
monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
|
|
59
|
+
monkeypatch.setattr(config_module, "_warned_undeclared", False)
|
|
60
|
+
cfg = Config()
|
|
61
|
+
with caplog.at_level("WARNING", logger="xbrlkit.config"):
|
|
62
|
+
for _ in range(3):
|
|
63
|
+
cfg.sec_headers
|
|
64
|
+
warnings = [r for r in caplog.records if "SEC_GOV_USER_AGENT" in r.getMessage()]
|
|
65
|
+
assert len(warnings) == 1
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def test_a_declared_identity_never_warns(monkeypatch, caplog):
|
|
69
|
+
monkeypatch.setenv("SEC_GOV_USER_AGENT", "Acme Corp ops@acme.com")
|
|
70
|
+
monkeypatch.setattr(config_module, "_warned_undeclared", False)
|
|
71
|
+
with caplog.at_level("WARNING", logger="xbrlkit.config"):
|
|
72
|
+
Config().sec_headers
|
|
73
|
+
assert not caplog.records
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def test_sec_headers_pass_a_declared_identity_through(monkeypatch):
|
|
77
|
+
monkeypatch.setenv("SEC_GOV_USER_AGENT", "Acme Corp ops@acme.com")
|
|
78
|
+
assert Config().sec_headers == {"User-Agent": "Acme Corp ops@acme.com"}
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def test_dotenv_file_populates_config(tmp_path):
|
|
82
|
+
"""A ``.env`` loaded via ``load_dotenv`` flows into a fresh ``Config``."""
|
|
83
|
+
# load_dotenv mutates os.environ directly, so save/restore around it rather
|
|
84
|
+
# than relying on monkeypatch (which can't unwind that external mutation).
|
|
85
|
+
original = os.environ.pop("SEC_GOV_USER_AGENT", None)
|
|
86
|
+
try:
|
|
87
|
+
env = tmp_path / ".env"
|
|
88
|
+
env.write_text('SEC_GOV_USER_AGENT="Dotenv User dev@example.com"\n')
|
|
89
|
+
load_dotenv(dotenv_path=env, override=True)
|
|
90
|
+
assert Config().user_agent == "Dotenv User dev@example.com"
|
|
91
|
+
finally:
|
|
92
|
+
if original is None:
|
|
93
|
+
os.environ.pop("SEC_GOV_USER_AGENT", None)
|
|
94
|
+
else:
|
|
95
|
+
os.environ["SEC_GOV_USER_AGENT"] = original
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def test_env_example_template_is_tracked_and_documents_user_agent():
|
|
99
|
+
"""The tracked template must survive the ``.env*`` gitignore un-ignore."""
|
|
100
|
+
example = Path(__file__).resolve().parent.parent / ".env.example"
|
|
101
|
+
assert example.exists()
|
|
102
|
+
assert "SEC_GOV_USER_AGENT" in example.read_text()
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def test_default_identity_carries_no_personal_contact():
|
|
106
|
+
"""The fallback names the project and a reserved address, nobody's inbox."""
|
|
107
|
+
assert DEFAULT_USER_AGENT == "xbrlkit xbrlkit@example.com"
|
|
108
|
+
assert "github.com" not in DEFAULT_USER_AGENT
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def test_a_github_user_agent_warns(monkeypatch, caplog):
|
|
112
|
+
"""EDGAR 403s any User-Agent mentioning github.com, with no hint why."""
|
|
113
|
+
monkeypatch.setenv("SEC_GOV_USER_AGENT", "xbrlkit (+https://github.com/acme/x)")
|
|
114
|
+
monkeypatch.setattr(config_module, "_warned_github", False)
|
|
115
|
+
with caplog.at_level("WARNING", logger="xbrlkit.config"):
|
|
116
|
+
Config().sec_headers
|
|
117
|
+
assert any("github.com" in r.getMessage() for r in caplog.records)
|
|
@@ -27,6 +27,7 @@ from xbrlkit.model import (
|
|
|
27
27
|
)
|
|
28
28
|
from rdflib import RDF
|
|
29
29
|
|
|
30
|
+
from xbrlkit.serialize._kernel import context
|
|
30
31
|
from xbrlkit.serialize import (
|
|
31
32
|
build_holon_graph,
|
|
32
33
|
classify_network,
|
|
@@ -472,3 +473,33 @@ def test_holon_serialization_is_deterministic() -> None:
|
|
|
472
473
|
if isinstance(entry, dict) and isinstance(entry.get("@graph"), list):
|
|
473
474
|
ids = [n.get("@id", "") for n in entry["@graph"] if isinstance(n, dict)]
|
|
474
475
|
assert ids == sorted(ids)
|
|
476
|
+
|
|
477
|
+
|
|
478
|
+
def test_the_canonical_context_declares_each_term_once() -> None:
|
|
479
|
+
"""A repeated key in the context silently rebinds a term.
|
|
480
|
+
|
|
481
|
+
`serialize/_kernel/` is a vendored fork and is excluded from ruff, so F601 —
|
|
482
|
+
which is enabled and does catch this — never runs on it. That is how a second
|
|
483
|
+
`"label"` key shipped in 0.7.0 and shadowed `rdfs:label` with `rs:label`,
|
|
484
|
+
leaving one term meaning two predicates across two documents that both call
|
|
485
|
+
themselves holons. Lint cannot reach the file; this can.
|
|
486
|
+
"""
|
|
487
|
+
import ast
|
|
488
|
+
from pathlib import Path
|
|
489
|
+
|
|
490
|
+
source = Path(context.__file__).read_text()
|
|
491
|
+
tree = ast.parse(source)
|
|
492
|
+
for node in ast.walk(tree):
|
|
493
|
+
if not isinstance(node, ast.Dict):
|
|
494
|
+
continue
|
|
495
|
+
keys = [k.value for k in node.keys if isinstance(k, ast.Constant)]
|
|
496
|
+
duplicates = {k for k in keys if keys.count(k) > 1}
|
|
497
|
+
assert not duplicates, f"repeated context keys: {sorted(duplicates)}"
|
|
498
|
+
|
|
499
|
+
|
|
500
|
+
def test_the_standard_label_term_does_not_shadow_rdfs_label() -> None:
|
|
501
|
+
"""`label` is `rdfs:label` — the platform's holon context binds it that way
|
|
502
|
+
too, and the two must not disagree. XBRL's standard-role label is written
|
|
503
|
+
under its own name."""
|
|
504
|
+
assert context.CANONICAL_CONTEXT["label"] == "rdfs:label"
|
|
505
|
+
assert context.CANONICAL_CONTEXT["standardLabel"]["@id"].endswith("standardLabel")
|
|
@@ -13,6 +13,7 @@ from __future__ import annotations
|
|
|
13
13
|
|
|
14
14
|
import json
|
|
15
15
|
import os
|
|
16
|
+
import textwrap
|
|
16
17
|
from datetime import date
|
|
17
18
|
from pathlib import Path
|
|
18
19
|
|
|
@@ -1023,3 +1024,37 @@ def test_real_filing_round_trip() -> None:
|
|
|
1023
1024
|
assert tools.search_text(lf, "item 7")["total"] > 0
|
|
1024
1025
|
finally:
|
|
1025
1026
|
session.close()
|
|
1027
|
+
|
|
1028
|
+
|
|
1029
|
+
class TestStartupBanner:
|
|
1030
|
+
"""What ``xbrlkit serve`` tells the operator on the way up."""
|
|
1031
|
+
|
|
1032
|
+
def test_the_json_is_valid_and_tracks_the_live_url(self):
|
|
1033
|
+
"""Built from the running url, so a non-default port stays copy-pasteable."""
|
|
1034
|
+
from xbrlkit.serve.server import startup_banner
|
|
1035
|
+
|
|
1036
|
+
url = "http://127.0.0.1:9000/mcp"
|
|
1037
|
+
banner = startup_banner(url, "Acme Corp ops@acme.com")
|
|
1038
|
+
block = banner[banner.index("{") : banner.rindex("}") + 1]
|
|
1039
|
+
parsed = json.loads(textwrap.dedent(block))
|
|
1040
|
+
assert parsed == {"mcpServers": {"xbrlkit": {"type": "http", "url": url}}}
|
|
1041
|
+
|
|
1042
|
+
def test_it_offers_the_claude_code_command(self):
|
|
1043
|
+
from xbrlkit.serve.server import startup_banner
|
|
1044
|
+
|
|
1045
|
+
banner = startup_banner("http://127.0.0.1:8765/mcp", None)
|
|
1046
|
+
assert "claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp" in banner
|
|
1047
|
+
|
|
1048
|
+
def test_an_undeclared_identity_names_the_default_and_the_fix(self):
|
|
1049
|
+
from xbrlkit.config import DEFAULT_USER_AGENT
|
|
1050
|
+
from xbrlkit.serve.server import identity_lines
|
|
1051
|
+
|
|
1052
|
+
text = "\n".join(identity_lines(None))
|
|
1053
|
+
assert DEFAULT_USER_AGENT in text
|
|
1054
|
+
assert "SEC_GOV_USER_AGENT=" in text
|
|
1055
|
+
|
|
1056
|
+
def test_a_declared_identity_is_echoed_without_advice(self):
|
|
1057
|
+
from xbrlkit.serve.server import identity_lines
|
|
1058
|
+
|
|
1059
|
+
lines = identity_lines("Acme Corp ops@acme.com")
|
|
1060
|
+
assert lines == ["SEC identity: Acme Corp ops@acme.com"]
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
"""Standalone configuration — replaces the robosystems ``config.env`` coupling.
|
|
2
|
+
|
|
3
|
+
The SEC adapter reads user-agent / base URLs / cache dirs from the platform's
|
|
4
|
+
central env config. This package is platform-free, so those settings live here
|
|
5
|
+
(env-overridable, or constructed explicitly by the CLI) instead.
|
|
6
|
+
|
|
7
|
+
SEC fair-access asks for a ``User-Agent`` that identifies you with contact
|
|
8
|
+
info. Set ``SEC_GOV_USER_AGENT`` (e.g. ``"Acme Corp ops@acme.com"``) and your
|
|
9
|
+
traffic is attributed to you. Leave it unset and EDGAR still works, under a
|
|
10
|
+
default that names the project: SEC rate limits per IP, so the shared string
|
|
11
|
+
costs no one else their budget. It is a courtesy worth extending anyway, so
|
|
12
|
+
the first unattributed EDGAR fetch of a process says so once, on stderr.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import logging
|
|
18
|
+
import os
|
|
19
|
+
from dataclasses import dataclass, field
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
|
|
22
|
+
# The fallback identity: the project name and a placeholder address, carrying
|
|
23
|
+
# nobody's real contact details — a default holding a person's address would
|
|
24
|
+
# put it on every install's traffic. ``example.com`` is reserved (RFC 2606),
|
|
25
|
+
# so it can never reach a stranger's inbox. Reaching a real one is what
|
|
26
|
+
# SEC_GOV_USER_AGENT is for, and the warning below asks for it.
|
|
27
|
+
#
|
|
28
|
+
# Deliberately no repository URL: EDGAR answers 403 to any User-Agent
|
|
29
|
+
# containing "github.com" (see GITHUB_UA_HELP), whatever else it says.
|
|
30
|
+
DEFAULT_USER_AGENT = "xbrlkit xbrlkit@example.com"
|
|
31
|
+
|
|
32
|
+
GITHUB_UA_HELP = (
|
|
33
|
+
"SEC_GOV_USER_AGENT contains 'github.com', which EDGAR refuses with HTTP "
|
|
34
|
+
"403 no matter what else the header says. Use a name and email instead, "
|
|
35
|
+
"e.g. 'Acme Corp ops@acme.com'."
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
SEC_IDENTITY_HELP = (
|
|
39
|
+
"xbrlkit is fetching from sec.gov under its default User-Agent. SEC fair "
|
|
40
|
+
"access asks you to identify yourself with contact info; set "
|
|
41
|
+
"SEC_GOV_USER_AGENT to a name and email you control:\n"
|
|
42
|
+
" export SEC_GOV_USER_AGENT='Acme Corp ops@acme.com'\n"
|
|
43
|
+
"or pass --user-agent. For an MCP client the server's own env block carries "
|
|
44
|
+
"it; see the README. Nothing outside EDGAR needs it."
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _default_cache_dir() -> Path:
|
|
49
|
+
override = os.environ.get("XBRL_HOLON_CACHE_DIR")
|
|
50
|
+
if override:
|
|
51
|
+
return Path(override)
|
|
52
|
+
return Path.home() / ".cache" / "xbrlkit"
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass(frozen=True)
|
|
56
|
+
class Config:
|
|
57
|
+
"""Runtime settings. Immutable; the CLI builds one per invocation."""
|
|
58
|
+
|
|
59
|
+
# The operator's own identity, or ``None`` until they declare one. Only the
|
|
60
|
+
# SEC clients care; everything else is happy with the default.
|
|
61
|
+
user_agent: str | None = field(
|
|
62
|
+
default_factory=lambda: os.environ.get("SEC_GOV_USER_AGENT") or None
|
|
63
|
+
)
|
|
64
|
+
sec_base_url: str = "https://www.sec.gov"
|
|
65
|
+
sec_data_url: str = "https://data.sec.gov"
|
|
66
|
+
# XBRL International's public index of filings outside EDGAR — ESEF and the
|
|
67
|
+
# national regimes that publish through it. Open, and it asks for no key.
|
|
68
|
+
filings_base_url: str = "https://filings.xbrl.org"
|
|
69
|
+
request_timeout: int = 30
|
|
70
|
+
rate_limit_per_sec: float = 5.0
|
|
71
|
+
# EDGAR answers a throttled client with an empty 200 as often as a 429;
|
|
72
|
+
# this is the wait before the one retry either gets.
|
|
73
|
+
throttle_backoff_s: float = field(
|
|
74
|
+
default_factory=lambda: float(os.environ.get("XBRLKIT_THROTTLE_BACKOFF", "45"))
|
|
75
|
+
)
|
|
76
|
+
cache_dir: Path = field(default_factory=_default_cache_dir)
|
|
77
|
+
# Arelle's DTS fetches: per-fetch timeout, and whether to fetch at all.
|
|
78
|
+
arelle_timeout: int = field(
|
|
79
|
+
default_factory=lambda: int(os.environ.get("XBRLKIT_ARELLE_TIMEOUT", "30"))
|
|
80
|
+
)
|
|
81
|
+
arelle_offline: bool = field(
|
|
82
|
+
default_factory=lambda: (
|
|
83
|
+
os.environ.get("XBRLKIT_ARELLE_OFFLINE", "").lower() in ("1", "true", "yes")
|
|
84
|
+
)
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
@property
|
|
88
|
+
def arelle_cache_dir(self) -> Path:
|
|
89
|
+
override = os.environ.get("XBRLKIT_ARELLE_CACHE_DIR")
|
|
90
|
+
return Path(override) if override else self.cache_dir / "arelle"
|
|
91
|
+
|
|
92
|
+
def identity(self) -> str | None:
|
|
93
|
+
"""The declared identity, or ``None``.
|
|
94
|
+
|
|
95
|
+
Falls back to the environment so an identity set after this config was
|
|
96
|
+
built still counts — the module-level ``CONFIG`` is created at import,
|
|
97
|
+
which is often before a host has loaded its env.
|
|
98
|
+
"""
|
|
99
|
+
declared = self.user_agent or os.environ.get("SEC_GOV_USER_AGENT")
|
|
100
|
+
if not declared or not declared.strip():
|
|
101
|
+
return None
|
|
102
|
+
declared = declared.strip()
|
|
103
|
+
if "github.com" in declared.lower():
|
|
104
|
+
warn_github_user_agent()
|
|
105
|
+
return declared
|
|
106
|
+
|
|
107
|
+
@property
|
|
108
|
+
def headers(self) -> dict[str, str]:
|
|
109
|
+
"""Headers for hosts that require no declared identity."""
|
|
110
|
+
return {"User-Agent": self.identity() or DEFAULT_USER_AGENT}
|
|
111
|
+
|
|
112
|
+
@property
|
|
113
|
+
def sec_headers(self) -> dict[str, str]:
|
|
114
|
+
"""Headers for sec.gov, warning once when no identity has been declared."""
|
|
115
|
+
identity = self.identity()
|
|
116
|
+
if identity is None:
|
|
117
|
+
warn_undeclared_sec_identity()
|
|
118
|
+
return {"User-Agent": DEFAULT_USER_AGENT}
|
|
119
|
+
return {"User-Agent": identity}
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
CONFIG = Config()
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
logger = logging.getLogger(__name__)
|
|
126
|
+
_warned_undeclared = False
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def warn_undeclared_sec_identity() -> None:
|
|
130
|
+
"""Say once per process that EDGAR is being fetched unattributed.
|
|
131
|
+
|
|
132
|
+
Once, because this sits behind every EDGAR request and a warning repeated a
|
|
133
|
+
few hundred times through a corpus run is noise the reader learns to skip.
|
|
134
|
+
"""
|
|
135
|
+
global _warned_undeclared
|
|
136
|
+
if _warned_undeclared:
|
|
137
|
+
return
|
|
138
|
+
_warned_undeclared = True
|
|
139
|
+
logger.warning("%s", SEC_IDENTITY_HELP)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
_warned_github = False
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def warn_github_user_agent() -> None:
|
|
146
|
+
"""Say once that a github.com User-Agent is refused by EDGAR.
|
|
147
|
+
|
|
148
|
+
The failure is otherwise a bare 403 with nothing pointing at the header.
|
|
149
|
+
"""
|
|
150
|
+
global _warned_github
|
|
151
|
+
if _warned_github:
|
|
152
|
+
return
|
|
153
|
+
_warned_github = True
|
|
154
|
+
logger.warning("%s", GITHUB_UA_HELP)
|
|
@@ -81,6 +81,10 @@ LABEL_TERM_ROLES: dict[str, str] = {
|
|
|
81
81
|
label_type.split(":", 1)[-1]: role for role, label_type in LABEL_ROLE_TYPES.items()
|
|
82
82
|
}
|
|
83
83
|
STANDARD_LABEL_ROLE_URI = "http://www.xbrl.org/2003/role/label"
|
|
84
|
+
# The emitter names the standard-role label `standardLabel`; `label` is read as
|
|
85
|
+
# well, because holons written by 0.7.0-0.7.2 used it.
|
|
86
|
+
LABEL_TERM_ROLES["standardLabel"] = STANDARD_LABEL_ROLE_URI
|
|
87
|
+
LABEL_TERM_ROLES["label"] = STANDARD_LABEL_ROLE_URI
|
|
84
88
|
DOCUMENTATION_LABEL_ROLE = "http://www.xbrl.org/2003/role/documentation"
|
|
85
89
|
|
|
86
90
|
PARENT_CHILD_ARCROLE = "http://www.xbrl.org/2003/arcrole/parent-child"
|
|
@@ -83,7 +83,7 @@ class EdgarClient:
|
|
|
83
83
|
def __init__(self, config: Config = CONFIG) -> None:
|
|
84
84
|
self.config: Config = config
|
|
85
85
|
self._session: requests.Session = requests.Session()
|
|
86
|
-
self._session.headers.update(config.
|
|
86
|
+
self._session.headers.update(config.sec_headers)
|
|
87
87
|
self._limiter: RateLimiter = RateLimiter(config.rate_limit_per_sec)
|
|
88
88
|
self._ticker_map: dict[str, str] | None = None
|
|
89
89
|
|
|
@@ -82,7 +82,7 @@ class EftsClient:
|
|
|
82
82
|
def __init__(self, config: Config = CONFIG, per_sec: float | None = None) -> None:
|
|
83
83
|
self.config: Config = config
|
|
84
84
|
self._session: requests.Session = requests.Session()
|
|
85
|
-
self._session.headers.update(config.
|
|
85
|
+
self._session.headers.update(config.sec_headers)
|
|
86
86
|
self._limiter: RateLimiter = RateLimiter(
|
|
87
87
|
config.rate_limit_per_sec if per_sec is None else per_sec
|
|
88
88
|
)
|
|
@@ -140,8 +140,12 @@ CANONICAL_CONTEXT: dict = {
|
|
|
140
140
|
"prefLabel": "skos:prefLabel",
|
|
141
141
|
"documentation": "rdfs:comment",
|
|
142
142
|
# The standard-role label, written beside `skos:prefLabel` because only
|
|
143
|
-
# this one can carry the language the label was authored in.
|
|
144
|
-
|
|
143
|
+
# this one can carry the language the label was authored in. Named
|
|
144
|
+
# `standardLabel` — XBRL's own name for the role — because `label` is bound
|
|
145
|
+
# to `rdfs:label` by the platform's holon context, and one key meaning two
|
|
146
|
+
# predicates across two documents that both call themselves holons is worse
|
|
147
|
+
# than a longer name.
|
|
148
|
+
"standardLabel": {"@id": f"{RS_VOCAB}standardLabel"},
|
|
145
149
|
# Every other XBRL label role, one term each. A label is a literal with a
|
|
146
150
|
# role, so it is one triple rather than a node: reifying them would add a
|
|
147
151
|
# node per label, half again as many nodes as a report has.
|