https://github.com/lukateras/python-fraudrecord
FraudRecord Query API client for Python
https://github.com/lukateras/python-fraudrecord
api-client asyncio cli fraudrecord pypi-package python python-library
Last synced: 2 months ago
JSON representation
FraudRecord Query API client for Python
- Host: GitHub
- URL: https://github.com/lukateras/python-fraudrecord
- Owner: lukateras
- License: other
- Created: 2022-09-01T06:55:03.000Z (about 3 years ago)
- Default Branch: trunk
- Last Pushed: 2025-01-03T21:31:15.000Z (9 months ago)
- Last Synced: 2025-02-22T01:35:11.347Z (8 months ago)
- Topics: api-client, asyncio, cli, fraudrecord, pypi-package, python, python-library
- Language: Python
- Homepage: https://pypi.org/project/fraudrecord/
- Size: 39.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# `python-fraudrecord`
FraudRecord Query API client for Python.
Maintained, stable, and tested as of January 2025. There will never be any
breaking changes.
## Usage
Install from PyPI:
```sh
$ pip install fraudrecord
```
To use the non-blocking client include the `aio` extra:
```sh
$ pip install fraudrecord[aio]
```
### Example
Using the blocking client:
```python
from fraudrecord.query import query as fraudrecord_query
if __name__ == "__main__":
api_code = "a51ff508c331b7e9" # XXX: use your own
print(fraudrecord_query(api_code, email="example@example.com"))
```
Using the non-blocking client:
```python
import asyncio
from fraudrecord.query_aio import query as fraudrecord_query
async def main():
api_code = "a51ff508c331b7e9" # XXX: use your own
response = await fraudrecord_query(api_code, email="example@example.com")
print(response)
if __name__ == "__main__":
asyncio.run(main())
```
Using the CLI:
```sh
$ FRAUDRECORD_API_CODE=a51ff508c331b7e9 fraudrecord-query --email=example@example.com
```
## Documentation
### `fraudrecord.hash`
FraudRecord hashing scheme as described on .
32,000 iterations of SHA-1. Case- and whitespace- insensitive: the input is
downcased and stripped of all whitespace. The hexadecimal digest of each
iteration is prefixed with `fraudrecord-` and fed into the next.
- function `hexdigest(s: str) -> str`
Returns the hexadecimal digest of the input string.
### `fraudrecord.model`
FraudRecord data model.
- type `APICode`
API code. Lowercase alphanumeric string of 16 characters. Get one by signing
up with FraudRecord and creating a reporter profile.
- type `Reliability`
Reliability score. Decimal; either 0.0 (if no reports have been submitted) or
within 1.0 and 10.0 with one digit after the decimal point.
- type `ReportCode`
Report code. Lowercase alphanumeric string of 16 characters.
- constant `ENDPOINT: HttpUrl`
The API endpoint URL.
- function `query_url(api_code: APICode, **data_vars: str) -> HttpUrl`
Given an API code and (non-hashed) data variables, returns the corresponding
Query API URL.
Data variables are arbitrary bits of information about someone as described
on under "Data variables". Well-known
data variable names are:
+ `name`: full name
+ `company`: company name
+ `email`: email address
+ `address`: postal address
+ `phone`: phone number
+ `ip`: registration IP address
+ `hostname`: server hostname
+ `accountuser`: hosting account username
+ `accountpass`: hosting account password
+ `domain`: domain name without `www.`
+ `paypalemail`: PayPal email address
+ `ccname`: name on the credit card
+ `ccnumber`: credit card number
- function `report_url(report_code: ReportCode) -> HttpUrl`
Given a report code, returns the corresponding human-readable report URL.
- class `QueryResponse`
Query API response.
+ field `total_points: NonNegativeInt`
Total points (severity scores from 1 to 10 summed across all reports).
+ field `total_reports: NonNegativeInt`
Total reports.
+ field `reliability: Reliability`
Reliability score.
+ field `report_url: HttpUrl`
Report URL.
Example: https://www.fraudrecord.com/api/?showreport=0f5dac5aab7762e6
+ class method `parse(s: str) -> QueryResponse`
Parses the input string containing a Query API response body into a
`QueryResponse` object.
### `fraudrecord.query`
Blocking FraudRecord Query API client.
- function `query(api_code: APICode, **data_vars: str) -> QueryResponse`
Makes a request to the Query API and returns a `QueryResponse`.
### `fraudrecord.query.cli`
FraudRecord Query API command-line interface.
Usage: `fraudrecord-query --DATA_VARIABLE=VALUE ...`
`FRAUDRECORD_API_CODE` environment variable must be set to a valid FraudRecord
API code. Get one by signing up with FraudRecord and creating a reporter profile.
### `fraudrecord.query_aio`
Non-blocking FraudRecord Query API client.
*Requires the `aio` extra to be installed.*
- async function `query(api_code: APICode, **data_vars: str) -> QueryResponse`
Makes a request to the Query API and returns a `QueryResponse`.
---
This package is intended for privacy research only. Reporting isn't and won't
be implemented.