Metadata-Version: 2.5
Name: varve-data
Version: 0.1.0
Summary: Download and use Varve Data: point-in-time US fundamentals and SEC filing events
Project-URL: Homepage, https://varvedata.com
Project-URL: Source, https://github.com/varve-data/varve-python
Project-URL: Documentation, https://varvedata.com/examples.html
Project-URL: Examples, https://github.com/varve-data/varve-examples
License-Expression: MIT
License-File: LICENSE
Keywords: backtesting,edgar,fundamentals,point-in-time,sec,xbrl
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=14
Requires-Dist: requests>=2.28
Provides-Extra: duckdb
Requires-Dist: duckdb>=1.0; extra == 'duckdb'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# varve-data

The Python client for [Varve Data](https://varvedata.com): point-in-time US company
fundamentals and SEC filing events, built directly from EDGAR.

It downloads your datasets (and keeps them current, fetching only files that changed),
loads any table as a pandas DataFrame or DuckDB view, and lines fundamentals up by the
date they became **public**, so a backtest never sees a number before it was filed.

```bash
pip install varve-data            # add [duckdb] for SQL over the full files
```

## Try it on the free sample (no key)

```python
import varvedata as vd

q = vd.load("quarterly", sample=True)          # 25 companies, full quarterly history
vd.snapshot("2024-10-31", ["revenue", "eps_diluted"], sample=True)
```

## Your data

Your personal account link (from the purchase email or the account page) is your key.

```bash
varve login        # paste the link once; stored in ~/.varve/key, readable only by you
varve sync         # download everything on your plan; rerun daily for Events updates
varve tables       # what's available
```

Or from Python: `vd.sync()`. Files go to `~/.varve/data` (set `VARVE_DATA` to change it).
A sync checks your plan, downloads only files whose checksum changed, verifies every
file, and unpacks the 13F positions archive.

## Loading tables

```python
q = vd.load("fundamentals_quarterly")                        # or just "quarterly"
ins = vd.load("insider_transactions",
              columns=["filed", "ticker", "code", "shares", "price", "value"],
              filters=[("code", "==", "P"), ("filed", ">=", pd.Timestamp("2024-01-01"))])
pos = vd.load("13f_positions", filters=[("period", "==", "2026-06-30")])
```

`columns` and `filters` are applied while reading the parquet file, so pulling a slice of
the 10-million-row insider table takes a fraction of a second.

```python
con = vd.connect()                                           # DuckDB, one view per table
con.sql("""select ticker, sum(value) as bought from events_insider_transactions
           where code = 'P' and filed >= '2026-01-01' group by 1 order by 2 desc limit 10""").df()
```

## Point-in-time helpers

| function | what it does |
|---|---|
| `vd.as_of(panel)` | For each (varve_id, date) row, attach the newest quarter that was public on that date. |
| `vd.snapshot(date)` | Every company's newest public quarter on one date. `max_age_days=200` keeps only companies still reporting. |
| `vd.ttm(q)` | Trailing-twelve-month figures from four consecutive quarters, dated when the fourth was filed. Works with `as_of` and `snapshot`. |
| `vd.map_tickers(df)` | (ticker, date) → varve_id and cik, using the company that held the ticker **on that date** (recycled tickers map correctly). |

A typical backtest join, starting from your own price data:

```python
prices = vd.map_tickers(prices, ticker_col="symbol", date_col="date")   # adds varve_id, cik
t = vd.ttm(vd.load("quarterly"))
panel = vd.as_of(prices, fields=["revenue", "net_income", "equity"], fundamentals=t)
panel["earnings_yield"] = panel["net_income"] / (panel["close"] * panel["shares_outstanding"])
```

With Fundamentals 0.3.0 the `factors` table has 20+ price-free factors (gross profitability, accruals,
asset growth, net share issuance, SUE, Piotroski F-score ...) already dated by `filed`:

```python
fac = vd.load("factors")
panel = vd.as_of(prices, fields=["gross_profitability", "accruals", "sue", "f_score"], fundamentals=fac)
```

Why it matters: lined up by `period_end` instead of filing date, 62% of company-months in
a typical backtest use a quarter that hadn't been filed yet. See the
[look-ahead bias study](https://varvedata.com/look-ahead-bias.html).

## More

* [Examples](https://github.com/varve-data/varve-examples): notebooks on point-in-time joins, identifiers, events and varve_id
* [Schema and data dictionary](https://varvedata.com/data.html)
* [Methodology](https://varvedata.com/downloads/methodology.pdf)

MIT licensed. The data itself is covered by your Varve Data licence.
