Metadata-Version: 2.1
Name: metric-builder
Version: 0.0.2
Summary: Utility for building templated metric extraction queries that can be traversed through time.
Home-page: UNKNOWN
Author: Philip Perold
Author-email: philip@spatialedge.co.za
License: UNKNOWN
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
Requires-Dist: cachetools (==3.1.1)
Requires-Dist: certifi (==2019.9.11)
Requires-Dist: chardet (==3.0.4)
Requires-Dist: coverage (==4.5.4)
Requires-Dist: google-api-core (==1.14.3)
Requires-Dist: google-auth (==1.6.3)
Requires-Dist: google-cloud-bigquery (==1.21.0)
Requires-Dist: google-cloud-core (==1.0.3)
Requires-Dist: google-resumable-media (==0.4.1)
Requires-Dist: googleapis-common-protos (==1.6.0)
Requires-Dist: idna (==2.8)
Requires-Dist: Jinja2 (==2.10.0)
Requires-Dist: MarkupSafe (==1.1.1)
Requires-Dist: protobuf (==3.10.0)
Requires-Dist: pyasn1 (==0.4.7)
Requires-Dist: pyasn1-modules (==0.2.7)
Requires-Dist: pytz (==2019.3)
Requires-Dist: requests (==2.22.0)
Requires-Dist: rsa (==4.0)
Requires-Dist: six (==1.12.0)
Requires-Dist: urllib3 (==1.25.6)

# Metric Builder

Utility for building templated metric extraction queries that can be traversed through time.

## Prerequisites

You will need the following to run this code:
  * Python 3

## Installation

To be determined...

## Usage

In order to extract a given metric, a `Metric` object needs to be instantiated:

```python
metric = Metric(
    query="""
        SELECT count(*) AS total
        FROM `project.dataset.table`
        WHERE DATETIME_TRUNC(created_datetime, DAY) = '{{ reference_time | format_date('%Y-%m-%d') }}'
    """,
    reader = BigQueryReader(json_credentials_path='/path/to/creds.json')
)
```

The `query` parameter is a templated query where you can format the `reference_time` `datetime` object to the required format using template filters.

The `reader` parameter is the object that is actually going to connect to the desired database and perform the queries.

The `metric` object can now be used to fetch metrics for a given point in time as follows:

```python
result = metric.fetch(reference_time=datetime.date(2019, 10, 21))
```

The result is returned as a list of dictionaries.

### Template filters

[Jinja2](https://jinja.palletsprojects.com/en/2.10.x/) is used as the templating engine. All built in Jinja filters are thus available. Relevant custom template filters have been added though for convenience:

#### format_date

Specify format of datetime:

```
'{{ reference_time | format_date('%Y-%m-%d') }}'
```

#### day_delta

Change a given datetime object by a specified number of days:

```
'{{ reference_time | day_delta(-7) | format_date('%Y-%m-%d') }}'
```

### Readers

Any reader will implement the following method that is used to execute queries:

```python
def execute(self, query) -> List[Dict[str, Any]]:
    ...
```

#### BigQueryReader

The underlying client is required to be authenticated with the necessary priviledges to read from the requested BigQuery tables.

If you authenticate with:

```bash
gcloud auth login
```

or

```bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
```

then you can just instantiate your `Reader` like this:

```python
reader = BigQueryReader()
```

The other option is to explicitly authenticate with a service account key file:

```python
reader = BigQueryReader(json_credentials_path='/path/to/creds.json')
```

#### HiveReader

Coming soon...

