finbrain-python 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

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.
Files changed (11) hide show
  1. finbrain/aio/endpoints/house_trades.py +13 -1
  2. finbrain/aio/endpoints/screener.py +14 -2
  3. finbrain/aio/endpoints/senate_trades.py +13 -1
  4. finbrain/endpoints/house_trades.py +24 -0
  5. finbrain/endpoints/screener.py +14 -2
  6. finbrain/endpoints/senate_trades.py +24 -0
  7. {finbrain_python-0.2.5.dist-info → finbrain_python-0.2.7.dist-info}/METADATA +35 -1
  8. {finbrain_python-0.2.5.dist-info → finbrain_python-0.2.7.dist-info}/RECORD +11 -11
  9. {finbrain_python-0.2.5.dist-info → finbrain_python-0.2.7.dist-info}/WHEEL +1 -1
  10. {finbrain_python-0.2.5.dist-info → finbrain_python-0.2.7.dist-info}/licenses/LICENSE +0 -0
  11. {finbrain_python-0.2.5.dist-info → finbrain_python-0.2.7.dist-info}/top_level.txt +0 -0
finbrain/aio/endpoints/house_trades.py CHANGED
@@ -24,7 +24,19 @@ class AsyncHouseTradesAPI:
24
24
  limit: int | None = None,
25
25
  as_dataframe: bool = False,
26
26
  ) -> Dict[str, Any] | pd.DataFrame:
27
- """Fetch House-member trades for a symbol (async)."""
27
+ """
28
+ Fetch House-member trades for a symbol (async).
29
+
30
+ Each row in ``trades`` carries ``date`` (the transaction date),
31
+ ``politician``, ``transactionType``, ``amount`` and
32
+ ``disclosureDate`` — the date the trade was publicly disclosed in the
33
+ member's periodic transaction report. ``disclosureDate`` is ``None``
34
+ for historical rows collected before the field was captured (``NaN``
35
+ in the DataFrame branch on newer pandas — use ``pandas.isna``).
36
+
37
+ ``date_from``/``date_to`` bound the transaction date, not the
38
+ disclosure date.
39
+ """
28
40
  params: Dict[str, str] = {}
29
41
  if date_from:
30
42
  params["startDate"] = to_datestr(date_from)
finbrain/aio/endpoints/screener.py CHANGED
@@ -107,7 +107,13 @@ class AsyncScreenerAPI:
107
107
  limit: int | None = None,
108
108
  as_dataframe: bool = False,
109
109
  ) -> List[Dict[str, Any]] | pd.DataFrame:
110
- """Screen House trades across all tickers."""
110
+ """
111
+ Screen House trades across all tickers.
112
+
113
+ Rows carry ``symbol``, ``name``, ``date``, ``politician``,
114
+ ``transactionType``, ``amount`` and ``disclosureDate`` (the public
115
+ disclosure date, ``None`` on historical rows).
116
+ """
111
117
  params = self._build_params(limit=limit)
112
118
  return await self._get("screener/congress/house", params, as_dataframe)
113
119
 
@@ -119,7 +125,13 @@ class AsyncScreenerAPI:
119
125
  limit: int | None = None,
120
126
  as_dataframe: bool = False,
121
127
  ) -> List[Dict[str, Any]] | pd.DataFrame:
122
- """Screen Senate trades across all tickers."""
128
+ """
129
+ Screen Senate trades across all tickers.
130
+
131
+ Rows carry ``symbol``, ``name``, ``date``, ``politician``,
132
+ ``transactionType``, ``amount`` and ``disclosureDate`` (the public
133
+ disclosure date, ``None`` on historical rows).
134
+ """
123
135
  params = self._build_params(limit=limit)
124
136
  return await self._get("screener/congress/senate", params, as_dataframe)
125
137
 
finbrain/aio/endpoints/senate_trades.py CHANGED
@@ -24,7 +24,19 @@ class AsyncSenateTradesAPI:
24
24
  limit: int | None = None,
25
25
  as_dataframe: bool = False,
26
26
  ) -> Dict[str, Any] | pd.DataFrame:
27
- """Fetch Senate-member trades for a symbol (async)."""
27
+ """
28
+ Fetch Senate-member trades for a symbol (async).
29
+
30
+ Each row in ``trades`` carries ``date`` (the transaction date),
31
+ ``politician``, ``transactionType``, ``amount`` and
32
+ ``disclosureDate`` — the date the trade was publicly disclosed in the
33
+ member's periodic transaction report. ``disclosureDate`` is ``None``
34
+ for historical rows collected before the field was captured (``NaN``
35
+ in the DataFrame branch on newer pandas — use ``pandas.isna``).
36
+
37
+ ``date_from``/``date_to`` bound the transaction date, not the
38
+ disclosure date.
39
+ """
28
40
  params: Dict[str, str] = {}
29
41
  if date_from:
30
42
  params["startDate"] = to_datestr(date_from)
finbrain/endpoints/house_trades.py CHANGED
@@ -49,6 +49,30 @@ class HouseTradesAPI:
49
49
  Returns
50
50
  -------
51
51
  dict | pandas.DataFrame
52
+ The raw dict has a ``trades`` list whose rows carry ``date``
53
+ (the transaction date), ``politician``, ``transactionType``,
54
+ ``amount`` and ``disclosureDate`` — the date the trade was
55
+ publicly disclosed in the member's periodic transaction report.
56
+ The gap between the two dates is the reporting lag.
57
+
58
+ ``disclosureDate`` is ``None`` for historical rows collected
59
+ before the field was captured upstream. In the DataFrame branch
60
+ ``date`` becomes the index and ``disclosureDate`` is a column
61
+ whose missing values read as ``None`` or ``NaN`` depending on the
62
+ pandas version — test them with :func:`pandas.isna`.
63
+
64
+ Notes
65
+ -----
66
+ ``date_from`` and ``date_to`` bound the **transaction** date, not the
67
+ disclosure date. A trade executed inside the window is returned even
68
+ if it was disclosed after ``date_to``.
69
+
70
+ Example row::
71
+
72
+ {"date": "2026-06-15", "politician": "Jane Doe",
73
+ "transactionType": "Purchase", "amount": "$1,001 - $15,000",
74
+ "disclosureDate": "2026-07-01"}
75
+
52
76
  """
53
77
  params: Dict[str, str] = {}
54
78
  if date_from:
finbrain/endpoints/screener.py CHANGED
@@ -112,7 +112,13 @@ class ScreenerAPI:
112
112
  limit: int | None = None,
113
113
  as_dataframe: bool = False,
114
114
  ) -> List[Dict[str, Any]] | pd.DataFrame:
115
- """Screen House trades across all tickers."""
115
+ """
116
+ Screen House trades across all tickers.
117
+
118
+ Rows carry ``symbol``, ``name``, ``date``, ``politician``,
119
+ ``transactionType``, ``amount`` and ``disclosureDate`` (the public
120
+ disclosure date, ``None`` on historical rows).
121
+ """
116
122
  params = self._build_params(limit=limit)
117
123
  return self._get("screener/congress/house", params, as_dataframe)
118
124
 
@@ -124,7 +130,13 @@ class ScreenerAPI:
124
130
  limit: int | None = None,
125
131
  as_dataframe: bool = False,
126
132
  ) -> List[Dict[str, Any]] | pd.DataFrame:
127
- """Screen Senate trades across all tickers."""
133
+ """
134
+ Screen Senate trades across all tickers.
135
+
136
+ Rows carry ``symbol``, ``name``, ``date``, ``politician``,
137
+ ``transactionType``, ``amount`` and ``disclosureDate`` (the public
138
+ disclosure date, ``None`` on historical rows).
139
+ """
128
140
  params = self._build_params(limit=limit)
129
141
  return self._get("screener/congress/senate", params, as_dataframe)
130
142
 
finbrain/endpoints/senate_trades.py CHANGED
@@ -49,6 +49,30 @@ class SenateTradesAPI:
49
49
  Returns
50
50
  -------
51
51
  dict | pandas.DataFrame
52
+ The raw dict has a ``trades`` list whose rows carry ``date``
53
+ (the transaction date), ``politician``, ``transactionType``,
54
+ ``amount`` and ``disclosureDate`` — the date the trade was
55
+ publicly disclosed in the member's periodic transaction report.
56
+ The gap between the two dates is the reporting lag.
57
+
58
+ ``disclosureDate`` is ``None`` for historical rows collected
59
+ before the field was captured upstream. In the DataFrame branch
60
+ ``date`` becomes the index and ``disclosureDate`` is a column
61
+ whose missing values read as ``None`` or ``NaN`` depending on the
62
+ pandas version — test them with :func:`pandas.isna`.
63
+
64
+ Notes
65
+ -----
66
+ ``date_from`` and ``date_to`` bound the **transaction** date, not the
67
+ disclosure date. A trade executed inside the window is returned even
68
+ if it was disclosed after ``date_to``.
69
+
70
+ Example row::
71
+
72
+ {"date": "2026-06-10", "politician": "Jane Doe",
73
+ "transactionType": "Purchase", "amount": "$1,001 - $15,000",
74
+ "disclosureDate": "2026-06-25"}
75
+
52
76
  """
53
77
  params: Dict[str, str] = {}
54
78
  if date_from:
{finbrain_python-0.2.5.dist-info → finbrain_python-0.2.7.dist-info}/METADATA RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: finbrain-python
3
- Version: 0.2.5
3
+ Version: 0.2.7
4
4
  Summary: Official Python client for the FinBrain API
5
5
  Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
6
6
  License-Expression: MIT
@@ -84,6 +84,7 @@ fb.analyst_ratings.ticker("AMZN",
84
84
  as_dataframe=True)
85
85
 
86
86
  # ---------- house trades ----------
87
+ # Rows include `disclosureDate` alongside the transaction `date`.
87
88
  fb.house_trades.ticker("AMZN",
88
89
  date_from="2025-01-01",
89
90
  date_to="2025-06-30",
@@ -155,12 +156,45 @@ fb.screener.insider_trading(limit=50)
155
156
  fb.screener.reddit_mentions(limit=100, as_dataframe=True)
156
157
  fb.screener.government_contracts(limit=100, as_dataframe=True)
157
158
  fb.screener.patent_filings(limit=100, as_dataframe=True)
159
+ fb.screener.congress_house(limit=50) # rows carry `disclosureDate`
160
+ fb.screener.congress_senate(limit=50)
158
161
 
159
162
  # ---------- recent data ----------
160
163
  fb.recent.news(limit=100, as_dataframe=True)
161
164
  fb.recent.analyst_ratings(limit=50)
162
165
  ```
163
166
 
167
+ ### Congressional trade dates
168
+
169
+ House and Senate trade rows carry **two** dates, and the gap between them is
170
+ the reporting lag — often weeks:
171
+
172
+ | Field | Meaning |
173
+ | ---------------- | ---------------------------------------------------------------- |
174
+ | `date` | Transaction date — when the member actually bought or sold |
175
+ | `disclosureDate` | Public disclosure date — when the periodic transaction report ran |
176
+
177
+ `disclosureDate` is `null` on historical rows collected before the field was
178
+ captured upstream. With `as_dataframe=True`, `date` is the **index** and
179
+ `disclosureDate` is a column whose missing values read as `None` or `NaN`
180
+ depending on your pandas version — test them with `pandas.isna()` rather than
181
+ `is None`. Note that `.dropna()` on such a frame will now discard every
182
+ historical row. The same field is present on `fb.screener.congress_house()`
183
+ and `fb.screener.congress_senate()` rows.
184
+
185
+ `date_from` / `date_to` bound the **transaction** date, not the disclosure
186
+ date — a trade executed inside the window is returned even if it was disclosed
187
+ after `date_to`.
188
+
189
+ ```python
190
+ trades = fb.house_trades.ticker("AMZN")["trades"]
191
+ lag_days = [
192
+ (pd.Timestamp(t["disclosureDate"]) - pd.Timestamp(t["date"])).days
193
+ for t in trades
194
+ if t["disclosureDate"]
195
+ ]
196
+ ```
197
+
164
198
  ## ⚡ Async Usage
165
199
 
166
200
  For async/await support, install with the `async` extra:
{finbrain_python-0.2.5.dist-info → finbrain_python-0.2.7.dist-info}/RECORD RENAMED
@@ -12,7 +12,7 @@ finbrain/aio/endpoints/app_ratings.py,sha256=QrJoLc7roTPRfInAEMwlr9vtxzruFJulGdB
12
12
  finbrain/aio/endpoints/available.py,sha256=rQuffHowNF7FrVV5Ds-KE5iFjdz0I_vD7Qk2_zY2WLo,2315
13
13
  finbrain/aio/endpoints/corporate_lobbying.py,sha256=4rILB9-W91n6v2UwOnlVeH-ulk4D8onamzdEJf--wko,1429
14
14
  finbrain/aio/endpoints/government_contracts.py,sha256=-jKXMHWrdG-4PszBSTQpK-i4SHpVZufPDBABMDB56Gk,1540
15
- finbrain/aio/endpoints/house_trades.py,sha256=HQVFnCI_rn9mdYWUTiU10iRoFxYdIeR7AhmqKrItndU,1427
15
+ finbrain/aio/endpoints/house_trades.py,sha256=c2g4TH8MeDhanUa9CnNWATdJK_W5PmogRrLRbK4wlVM,1982
16
16
  finbrain/aio/endpoints/insider_transactions.py,sha256=EBqHdvapYWvI53PM_sQy0caN2rbl7Qul4OmqzItMUR0,1437
17
17
  finbrain/aio/endpoints/linkedin_data.py,sha256=ucnkyNc1waiFHLxas1onPhxh9Y7ekcI_gOfUJ5gu1hI,1469
18
18
  finbrain/aio/endpoints/news.py,sha256=NJkcpoP8ngNsJdCzQab8yaXJzNe5ypYstzq3-mEHfqU,1446
@@ -21,8 +21,8 @@ finbrain/aio/endpoints/patent_filings.py,sha256=Wumihz2X7knKZNF36X9t0UJ8mk0ydg6H
21
21
  finbrain/aio/endpoints/predictions.py,sha256=BrUSmqy0v7ngXyoE_UHgqdght8qtJ8IRxAhk_s9UeR0,1285
22
22
  finbrain/aio/endpoints/recent.py,sha256=TSaAwf5w86O1plSmm4eg_gKSjSap2Z8rd2i7FAvgm90,2302
23
23
  finbrain/aio/endpoints/reddit_mentions.py,sha256=P9ToZRaRN521RJ9W2J8cBCySUsNT47ROe-8TTdVtlqA,1508
24
- finbrain/aio/endpoints/screener.py,sha256=bmBs0uTrt7B8byaGfLTg8IfZckE_5GpeoUty79bea4Q,10272
25
- finbrain/aio/endpoints/senate_trades.py,sha256=nhZd8R7Tclxzn-J4-ZWZ5onvBBd8pVOtiLfhKFtFBHw,1431
24
+ finbrain/aio/endpoints/screener.py,sha256=OzBiG5pxPID4Kgiv1UA7WAiNNr9iwdpzm_cczF8vPL0,10704
25
+ finbrain/aio/endpoints/senate_trades.py,sha256=Y6XbtX5O9AqPM4wFPvzbdiGXi9wx6SmbcxSxKFFcLRc,1986
26
26
  finbrain/aio/endpoints/sentiments.py,sha256=BXFT0jr5j0MnB65MXGxZK36BJLXMTuggkFF9A9eenEQ,1532
27
27
  finbrain/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
28
28
  finbrain/endpoints/_utils.py,sha256=wY8SKthpVernWlKwZfWoM8zZtQ3GS_hBQioH1Fk7RK4,1190
@@ -31,7 +31,7 @@ finbrain/endpoints/app_ratings.py,sha256=mbeKiJ87nNibnz9AT2kmH4fVFA4goEcld910abm
31
31
  finbrain/endpoints/available.py,sha256=3cXjDK1qE38RHAfQ2C14oD7l7dR8mhDtUcva3LzlK5s,3911
32
32
  finbrain/endpoints/corporate_lobbying.py,sha256=K4jFcgx2_PqxFSlSm2E0rxuunl7FjWEwk_S4nfjsMuw,2213
33
33
  finbrain/endpoints/government_contracts.py,sha256=jb96byPNK32AsEQWgCHMU7kAue9BFC539TH10JGfY7I,2343
34
- finbrain/endpoints/house_trades.py,sha256=x_C5Xc-Cj9CKdR2014XcP6G_zeXSWChwR8bKbkLzuGM,2235
34
+ finbrain/endpoints/house_trades.py,sha256=4WEviWj6SHcnrWEn8IdTwGT8SpaYcQJD1wVG_l6v3A4,3399
35
35
  finbrain/endpoints/insider_transactions.py,sha256=TU6EsSHIeams4OLJ9s8BpNuXeBnWPHghlp4enqkEFe8,2244
36
36
  finbrain/endpoints/linkedin_data.py,sha256=zcNboQ-Ejt_7Ncu3p9WCd-PsjEBFbojVaJZdkbaGT8Q,2215
37
37
  finbrain/endpoints/news.py,sha256=q4aaEiunrUbl1FF0JZuX9__cZWxm2r1-B9x-c8g4Ia8,1913
@@ -40,11 +40,11 @@ finbrain/endpoints/patent_filings.py,sha256=496m-3lnGc3twMAdcIDOyMWs3KwHD2W8c_vz
40
40
  finbrain/endpoints/predictions.py,sha256=og1RY68p4O71smogrx-M5FyGk8FVclBGP18BvttzbZk,2026
41
41
  finbrain/endpoints/recent.py,sha256=7D36oVRJKF5hkR42y6M6CiEMYksuFleZou1v86SbEfA,3004
42
42
  finbrain/endpoints/reddit_mentions.py,sha256=WiePVAyUbA0VpWOd22M2YTlDWOQITp8qUBraI29y6d4,2305
43
- finbrain/endpoints/screener.py,sha256=Ebw4Oksi8JNj1B8xX2Mh2U7MqO57telCpxx0rphPCe4,10166
44
- finbrain/endpoints/senate_trades.py,sha256=K6r_-Wt1HOs0dDXngHdj6Eo_UUJXAy5yE4EmmQbGaiU,2226
43
+ finbrain/endpoints/screener.py,sha256=CshSFgg2snMZ4Lo6RDrPxrhMDIeHCKduKwqyzHzIo-I,10598
44
+ finbrain/endpoints/senate_trades.py,sha256=u5IurzFNU4JEOs3CwlknulhSo3_wC7gWlX2baucxEO0,3390
45
45
  finbrain/endpoints/sentiments.py,sha256=sGGPaxzGGFvMOaYv3VSCmnG7H9v7OVlX7Vsndct8jhA,2606
46
- finbrain_python-0.2.5.dist-info/licenses/LICENSE,sha256=x71LjIUPbK7Y8YBulH_AXzEIX7BK90dgFL2zA6LBT-A,1069
47
- finbrain_python-0.2.5.dist-info/METADATA,sha256=Oxu3uLLP90SHboG4mMl2fQoJLDsqUTgGgu5XhMqhebs,16763
48
- finbrain_python-0.2.5.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
49
- finbrain_python-0.2.5.dist-info/top_level.txt,sha256=dCiQtTx3z2TtO_yQI6q3yODcdb-pABB-iEReJegVAv0,9
50
- finbrain_python-0.2.5.dist-info/RECORD,,
46
+ finbrain_python-0.2.7.dist-info/licenses/LICENSE,sha256=x71LjIUPbK7Y8YBulH_AXzEIX7BK90dgFL2zA6LBT-A,1069
47
+ finbrain_python-0.2.7.dist-info/METADATA,sha256=p-IT5YXQWHc_JORggxCyWDw_i-XG4VDf7FWjWENb5zE,18308
48
+ finbrain_python-0.2.7.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
49
+ finbrain_python-0.2.7.dist-info/top_level.txt,sha256=dCiQtTx3z2TtO_yQI6q3yODcdb-pABB-iEReJegVAv0,9
50
+ finbrain_python-0.2.7.dist-info/RECORD,,
{finbrain_python-0.2.5.dist-info → finbrain_python-0.2.7.dist-info}/WHEEL RENAMED
@@ -1,5 +1,5 @@
1
1
  Wheel-Version: 1.0
2
- Generator: setuptools (82.0.1)
2
+ Generator: setuptools (83.0.0)
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any
5
5