Skip to content

Latest commit

 

History

History
137 lines (100 loc) · 5.32 KB

readme.md

File metadata and controls

137 lines (100 loc) · 5.32 KB

51Degrees IP Intelligence Engines

51Degrees Python IP Intelligence

Developer Documentation

Introduction

This repository contains the IP intelligence engines for the Python implementation of the 51Degrees Pipeline API.

51Degrees IP Intelligence resolves an IP address to details about the network it belongs to (registered name, owner and country) and, with the Enterprise data file, the location associated with it.

The specification is also available on GitHub and is recommended reading if you wish to understand the concepts and design of this API.

Dependencies

The tested versions page shows the Python versions that we currently test against.

Git submodules

The on-premise engine wraps the native 51degrees-cxx library, which is included as the cxx git submodule. It has the data repository (data and evidence files used for testing) as its own submodule, at cxx/data. When cloning, use:

git clone --recurse-submodules https://github.com/51Degrees/51degrees-python.git

or if you have already cloned:

git submodule update --init --recursive

Data files

The on-premise engine requires a .ipi data file. The data repository's cxx/data/ip-intelligence folder holds the evidence files used for testing, and links to a freely available network-only data file (51Degrees-IPIV4AsnIpiV41.ipi), which the examples tests and AsnDataFileTests use. The linked files are not stored in a repository. Download them from the root of this repository by running:

sh cxx/data/get-data-files.sh ip-intelligence

or, in PowerShell:

./cxx/data/get-data-files.ps1 ip-intelligence

An example whose file is missing runs the script for that file itself. The on-premise unit tests default to assets/51Degrees-LiteIpiV41.ipi.

For the full set of properties (location, registration, etc.) an enterprise data file is required. To obtain one for testing, please contact us. Supply its path as a command line argument to the examples, or place it within the project space.

Note: the engine reads exactly one data file format version, set by FIFTYONE_DEGREES_IPI_TARGET_VERSION_MAJOR and _MINOR in the cxx submodule's src/ipi/ipi.c, and refuses any other as "an unsupported version". The ASN data file is downloaded from the Distributor, which always serves the latest one published, so AsnDataFileTests in test_ipintelligence.py fails when the engine cannot read the format 51Degrees publishes.

Folders

  • fiftyone_ipintelligence - umbrella package containing the IpIntelligencePipelineBuilder which builds cloud or on-premise pipelines depending on configuration.
  • fiftyone_ipintelligence_cloud - the cloud engine, which consumes the 51Degrees cloud service.
  • fiftyone_ipintelligence_onpremise - the on-premise engine, which wraps ip-intelligence-cxx via SWIG.
  • fiftyone_ipintelligence_shared - code shared between the engines.
  • fiftyone_ipintelligence_examples - usage examples for both engines.

Installation

From PyPI

pip install fiftyone_ipintelligence

From source

To build the on-premise native extension a C++17 compiler is required (MSVC on Windows, GCC/Clang elsewhere).

pip install -e fiftyone_ipintelligence_shared
pip install -e fiftyone_ipintelligence_cloud
pip install -e fiftyone_ipintelligence_onpremise
pip install -e fiftyone_ipintelligence
pip install -e fiftyone_ipintelligence_examples

Tests

Each package has its own test suite, run with pytest (or tox):

cd fiftyone_ipintelligence_cloud && python -m pytest tests
cd fiftyone_ipintelligence_onpremise && python -m pytest tests
cd fiftyone_ipintelligence_shared && python -m pytest tests
cd fiftyone_ipintelligence_examples && python -m pytest tests
  • The cloud tests run against a mocked cloud service, so no resource key is required. Set the _51DEGREES_RESOURCE_KEY environment variable to also exercise the live cloud service.
  • The on-premise tests require a data file (see Data files above). Set the _51DEGREES_IPI_PATH environment variable to use a data file from a custom location.

Examples

See fiftyone_ipintelligence_examples for console and web examples for both the cloud and on-premise engines.

License

This project is licensed under the European Union Public Licence v.1.2.