Metadata-Version: 2.4
Name: factpages-py
Version: 0.1.4
Summary: Python library for Norwegian Petroleum Factpages data
Project-URL: Homepage, https://github.com/kkollsga/factpages-py
Project-URL: Documentation, https://github.com/kkollsga/factpages-py#readme
Project-URL: Repository, https://github.com/kkollsga/factpages-py.git
Project-URL: Issues, https://github.com/kkollsga/factpages-py/issues
Author: Norwegian Petroleum Data Community
License-Expression: MIT
Keywords: api,discovery,field,gas,ncs,norway,npd,offshore,oil,petroleum,sodir,wellbore
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: pyarrow>=12.0.0
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: geo
Requires-Dist: geopandas>=0.12.0; extra == 'geo'
Requires-Dist: shapely>=2.0.0; extra == 'geo'
Description-Content-Type: text/markdown

# factpages-py

Python library for Norwegian Petroleum Factpages data.

Access petroleum data from the Norwegian Continental Shelf including wellbores, discoveries, fields, production data, licensing, and more.

## Installation

```bash
pip install factpages-py
```

## Quick Start

```python
from factpages_py import Factpages

fp = Factpages()

# Sync data from API
fp.sync()

# Access entities
troll = fp.field("troll")
print(troll.operator)
print(troll.partners)

# Get production data
production = troll.production(2025, 8)

# Raw DataFrame access
fields_df = fp.db.get('field')
discoveries_df = fp.db.get('discovery')
```

## Available Datasets

The API provides access to 100+ datasets:

| Category | Examples | Records |
|----------|----------|---------|
| **Core Entities** | discovery, field, wellbore, facility | 12K+ |
| **Production** | field_production_monthly, field_reserves | 10K+ |
| **Wellbore Details** | wellbore_chrono_strat, wellbore_core_photo | 200K+ |
| **Licensing** | licence, licence_licensee_history | 130K+ |
| **Seismic** | seismic_acquisition, seismic_acquisition_3d | 60K+ |
| **Stratigraphy** | strat_litho, strat_chrono | 300+ |

```python
# List all available tables
fp.db.list_tables()

# Get specific dataset
wellbores = fp.db.get('wellbore')
```

## Features

- **Simple API**: Download and access data easily
- **Pandas Integration**: Returns DataFrames ready for analysis
- **Entity Access**: High-level entity objects with properties and relationships
- **Graph Export**: Export data for knowledge graph construction
- **Geometry Support**: Includes GeoJSON geometries where available
- **Local Caching**: Data cached locally in Parquet format

## Graph Integration

Export data for knowledge graph libraries like rusty-graph:

```python
from factpages_py import Factpages
import rusty_graph

fp = Factpages()
fp.sync()

graph = rusty_graph.KnowledgeGraph()

# One-liner bulk loading
export = fp.graph.export_for_graph()
graph.add_nodes_bulk(export['nodes'])
graph.add_connections_from_source(export['connections'])
```

## Examples

### Entity Access

```python
# Get field by name
troll = fp.field("troll")
print(f"Operator: {troll.operator}")
print(f"Status: {troll.status}")

# Get wellbore
wellbore = fp.wellbore("31/2-1")
print(f"Depth: {wellbore.total_depth}m")
```

### Raw Data Access

```python
# Get DataFrame directly
fields = fp.db.get('field')
discoveries = fp.db.get('discovery')

# Filter data
producing = fields[fields['fldCurrentActivityStatus'] == 'Producing']
```

### Sync Specific Tables

```python
# Sync only specific tables
fp.sync(['field', 'discovery', 'wellbore'])

# Sync all tables
fp.sync()
```

## License

MIT License

## Acknowledgments

Data provided by the [Norwegian Offshore Directorate](https://www.sodir.no/) (Sodir).
