This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description
# Python Filterparams #

Filterparams is a library for parsing URL paramters for filter
purposes in a backend. It provides a syntax to map SQL-like
queries on top of the query parameters and parses it into a
python object.

This is a helper library for providing filter collection APIs.
The primary use case for developing the library is to
use it with a REST-API which uses the [JSONAPI](http://jsonapi.org/)
standard. Because of this the syntax is completely compatible with
the standard and encapsulates everything in the `filter` query
parameter.

## Example ##

Given the URL (non URL escaped for better readability):
```
/users?filter[param][name][like][no_default_name]=doe&filter[param][first_name]=doe%&filter[binding]=(!no_brand_name&first_name)&filter[order]=name&filter[order]=desc(first_name)
```

It can be parsed by the given function:

```python
from urllib.parse import urlsplit, parse_qs
from filterparams import build_parser

url = urlsplit(
'/users?filter[param][name][like][no_default_name]=doe'
'&filter[param][first_name]=doe%&filter[binding]='
'(!no_brand_name&first_name)&filter[order]=name'
'&filter[order]=desc(first_name)'
)
params = parse_qs(url)

valid_filters = ['eq', 'like']
default_filter = 'eq'

parser = build_parser(
valid_filters=valid_filters,
default_filter=default_filter,
)

query = parser(params)
```

Would parse the data. You can access the parsed filters through
`.param_order` and the orders through `.orders`. The param order
in this specific case would be resolved to:

```python
And(
left=Parameter(
name='name',
alias='no_default_name',
filter='like',
value='doe%',
),
right=Parameter(
name='first_name',
alias='first_name',
filter='eq',
value='doe',
)
)
```

The orders would be:

```python
[Order(name='name', direction='asc'),
Order(name='first_name', direction='desc')]
```

## Syntax ##

All arguments must be prefixed by "filter". It is possible to
query for specific data with filters, apply orders to the result
and to combine filters through AND, NOT and OR bindings.

The syntax builds under the filter parameter a virtual object.
The keys of the object are simulated through specifying `[{key}]`
in the passed query parameter. Thus `filter[param]` would point
to the param key in the filter object.

### Filter specification ###

The solution supports to query data through the `param` subkey.

```
filter[param][{parameter_name}][{operation}][{alias}] = {to_query_value}
```

The `operation` and `alias` parameters may be omitted. If no
`alias` is provided the given parameter name is used for it.
If no `operation` is given, the default one is used (in the
example this would be equal).

Example:
```
filter[param][phone_number][like]=001%
```

This would add a filter to all phone numbers which start with "001".

### Filter binding ###

Per default all filters are combined through AND clauses.
You can change that by specifying the `filter[binding]` argument.

This is where the aliases which you can define come into place.
The binding provides means to combine filters with AND and OR.
Also you are able to negate filters here.

The filters are addressed by their alias or name, if no alias is
provided.

If you have a filter `search_for_name`, `search_for_phone_number`
and `search_for_account_number` defined you can say
`search_for_name OR NOT search_for_number AND search_for_account_number`
by specifying the following filter:

```
filter[binding]=search_for_name|(!search_for_phone_number&search_for_account_number)
```

Even though the brackets are useless here, you can use them in
more complex filters.

The following table summarizes the possible configuration options:
<table>
<thead>
<tr>
<th>Type</th>
<th>Symbol</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td>AND</td>
<td>&</td>
<td>a&b</td>
</tr>
<tr>
<td>OR</td>
<td>|</td>
<td>a|b</td>
</tr>
<tr>
<td>NOT</td>
<td>!</td>
<td>!a</td>
</tr>
<tr>
<td>Bracket</td>
<td>()</td>
<td>(a|b)&c</td>
</tr>
</tbody>
</table>

### Ordering ###

To specify a sort order of the results the `filter[order]` parameter
may be used. The value can be specified multiple times. To add
ordering you have to provide the name of the parameter which should
be ordered, not its alias!

If you want to order by `name`, `first_name` and in reverse order
`balance` you can do so by specifying the following query url
parameters:

```
filter[order]=name&filter[order]=first_name&filter[order]=desc(balance)
```

As you can see the `desc()` definition can be used to indicate
reverse ordering.

### Filter definition ###

Not every backend does or should support all possible filter
mechanisms. This is why the filters which should be accepted
by the backend have to be added before processing the query
parameters.

You can limit the allowed filters by building a parse through the
`filterparams.build_parser` function. You can configure the allowed
filters through the `valid_filters` definition. Additionally you
have to add the default filter by using the second `default_filter`
parameter.

```python
from filterparams import build_parser

valid_filters = ['eq', 'like']
default_filter = 'eq'

parser = build_parser(
valid_filters=valid_filters,
default_filter=default_filter,
)

query = parser({})
```

If you don't want any validation you can use the `parse` function.

```python
from filterparams import parse

query = parse({})
```

## Notes ##

- There do no yet exist any public projects which use this library to provide transparent mapping to an underlying
backend. I plan long-term to add another library which does use this package and provide a way to map it on sqlalchemy models.
If you are planning to do this or use it for other data mapping please contact me and I'll add a reference to it in
the README.
- The same as mentioned above is valid for client libraries, which generate the filter query structure in any language.
Again, as soon as the API is stable I'll probably add a JavaScript library.
- Depending on your backend it might not make sense to support all features (ordering, parameter binding) of the
language. You might still want to use it to parse your basic parameters though and ignore the rest.

## Used Libraries ##

For evaluating the filter params ordering the [funcparserlib](https://github.com/vlasovskikh/funcparserlib) ([MIT license](https://github.com/vlasovskikh/funcparserlib/blob/master/LICENSE))
module is used. Additionally the [Werkzeug](https://github.com/mitsuhiko/werkzeug/blob/master/LICENSE) package is used for supporting dicts with multiple values in the same key.

## Other Languages ##

This is a list of projects implementing the same API for other languages.
Currently this list only has one entry.

- Go - [go-filterparams](https://github.com/cbrand/go-filterparams)
Release History

Release History

1.0.2

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
filterparams-1.0.2-py2.7.egg (5.6 kB) Copy SHA256 Checksum SHA256 2.7 Egg Feb 16, 2016
filterparams-1.0.2-py2-none-any.whl (6.9 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Feb 16, 2016
filterparams-1.0.2-py3.1.egg (11.1 kB) Copy SHA256 Checksum SHA256 3.1 Egg Feb 16, 2016
filterparams-1.0.2-py3.2.egg (11.3 kB) Copy SHA256 Checksum SHA256 3.2 Egg Feb 16, 2016
filterparams-1.0.2-py3.3.egg (13.3 kB) Copy SHA256 Checksum SHA256 3.3 Egg Feb 16, 2016
filterparams-1.0.2-py3.4.egg (13.1 kB) Copy SHA256 Checksum SHA256 3.4 Egg Feb 16, 2016
filterparams-1.0.2-py3.5.egg (13.1 kB) Copy SHA256 Checksum SHA256 3.5 Egg Feb 16, 2016
filterparams-1.0.2-py3-none-any.whl (6.8 kB) Copy SHA256 Checksum SHA256 3.5 Wheel Feb 16, 2016
filterparams-1.0.2.tar.gz (9.9 kB) Copy SHA256 Checksum SHA256 Source Feb 16, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting