{ "info": { "author": "Eli Flesher", "author_email": "eli@eflee.us", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Environment :: Other Environment", "Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.4", "Topic :: Internet", "Topic :: Other/Nonlisted Topic" ], "description": "PyEchoIP\r\n========\r\n\r\nA generic library in python to get your external IP from sites around\r\nthe internet in a consistent manner. Using zopes interfaces, allows the\r\nuser to create their own sources. Features time-based caching,\r\nmulti-source verification and other features.\r\n\r\nUsing IP Providers\r\n------------------\r\n\r\nIP providers are the high-level interfaces to IPSources. They allow the\r\nuser an abstraction from the source provider and in fact allow them to\r\nuse multiple sources transparently.\r\n\r\nBy default all providers cache a response from one hour (3600 seconds)\r\nand will self-invalidate in the event that time passes or the users\r\nrequests an additional information key that is not present in the\r\ncurrent cache.\r\n\r\nNote: because different sources return different supplement information\r\nto the IP address, the users must know the key for which they're looking\r\nin order to make use of the information. This is one of the rougher\r\nedges of the code base because it is on the boundary of the intended\r\nscope. If you need a feature, please ask for it.\r\n\r\nIPProvider\r\n~~~~~~~~~~\r\n\r\nThe standard IPProvider checks a single source, provides and caches the\r\nanswer.\r\n\r\n::\r\n\r\n In [1]: import echoip\r\n In [2]: import echoip.sources\r\n In [3]: import echoip.providers\r\n In [4]: source_factory = echoip.sources.IPSourceFactory()\r\n In [5]: provider = echoip.providers.IPProvider()\r\n In [6]: for source in source_factory.get_sources():\r\n ...: provider.add_source(source)\r\n ...:\r\n In [7]: provider.get_ip()\r\n Out[7]: IPv4Address('67.171.19.153')\r\n\r\nUsage:\r\n\r\n::\r\n\r\n Type: type\r\n String form: \r\n Init definition: echoip.providers.IPProvider(self, source_list=None, cache_ttl=3600)\r\n Init docstring:\r\n The IPProvider takes one or more IPSources and returns the results from them . If one\r\n provider does not respond it will move on to the next. It ensures that the age of the\r\n response on no older than the cache_ttl.\r\n\r\n :param source_list: The list of sources to bootstrap the provider with\r\n :type source_list: list of IIPSource providers\r\n :param cache_ttl: the seconds the ip cache remains valid\r\n :type cache_ttl: int\r\n\r\nSome sources choose to provide additional information (like GeoIP\r\ninformation). That information is marshalled into a single dictionary\r\nbased and can be retrieved by get\\_info():\r\n\r\n::\r\n\r\n In [8]: provider.get_info()\r\n Out[8]:\r\n {u'city': u'Keb',\r\n u'country': u'CO',\r\n u'loc': u'27.6355,-22.3235'}\r\n\r\nFurther documenation:\r\n\r\nMultipleSourceIPProvider\r\n~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nThe MultipleSourceIPProvider checks with multiple sources. If and only\r\nif min\\_source\\_agreement (constructor parameter) sources agree on the\r\nIP address is the answer cached.\r\n\r\nNote: The IP is cached. The additional info from the sources are\r\ncombined into a single dictionary. Duplicate keys are overwritten in a\r\nnon-deterministic fashion. This provider is mostly useful for when you\r\nare distrustful of the IP results.\r\n\r\nThe provider is used the exact same way.\r\n\r\n::\r\n\r\n In [1]: import echoip\r\n In [2]: import echoip.sources\r\n In [3]: import echoip.providers\r\n In [4]: source_factory = echoip.sources.IPSourceFactory()\r\n In [5]: provider = echoip.providers.MultisourceIPProvider\r\n In [6]: for source in source_factory.get_sources():\r\n ...: provider.add_source(source)\r\n ...:\r\n In [7]: provider.get_ip()\r\n Out[7]: IPv4Address('67.171.19.153')\r\n\r\nUsage:\r\n\r\n::\r\n\r\n Type: type\r\n String form: \r\n File: /Users/eflee/Development/pyechoip/src/echoip/providers.py\r\n Init definition: echoip.providers.MultisourceIPProvider(self, source_list=None, cache_ttl=3600, min_source_agreement=2)\r\n Init docstring:\r\n The IPProvider takes one or more IPSources and returns the results from them if the minimum number of sources\r\n are in agreement regard the external IP.\r\n Additional info from multiple providers is extended into one dictionary.\r\n If one provider does not respond it will move on to the next. It ensures that the age of the\r\n response on no older than the cache_ttl.\r\n\r\n :param source_list: The list of sources to bootstrap the provider with\r\n :type source_list: list of IIPSource providers\r\n :param cache_ttl: the seconds the ip cache remains valid\r\n :param min_source_agreement: The minimum number of source that must be in agreement for an ip_fetch\r\n :type min_source_agreement: int\r\n\r\nFurther documenation:\r\n\r\nUsing IP Sources\r\n----------------\r\n\r\nIPSources are the low-level interface to the library. There is no\r\ncaching for IPSources and the only validation is the returned IP\r\naddress.\r\n\r\nThere are two (as of now) basic types: SimpleIPSources and JSONIPSources\r\nwhich seem to be the two most common interface types for the publicly\r\navailable services.\r\n\r\nIn addition to IPSources there is an IPSourceFactory that can generate\r\nconfigured sources for the list of built-ins below.\r\n\r\nFinally, there is an IIPSource interface for implementing customer\r\nsources.\r\n\r\nIIPSource (Interface)\r\n~~~~~~~~~~~~~~~~~~~~~\r\n\r\nI want to cover this in brief, this is the interface for implementing\r\ncustom sources. It is rather simple: the source must provide an ip\r\nattribute and an info attribute.\r\n\r\nThe ip attribute is the ipaddress.IPv4Address or ipaddress.IPv6Address\r\n(py2-ipaddress for Python2 or ipaddress for Python3) encapsulated ip\r\naddress returned from the API.\r\n\r\nThe info attribute is a key-value dictionary for all other results\r\nreturned from the API. There is no additional guarantees of cleanliness\r\nor format and this varries from source to source.\r\n\r\nSimpleIPSource\r\n~~~~~~~~~~~~~~\r\n\r\nThe SimpleIPSource handles sites like curlmyip.com that return only an\r\nstring IP. The class simply strips the whitespace from the string and\r\nvalidates it by instantiating it as an IPAddress.\r\n\r\n::\r\n\r\n In [1]: import echoip.sources\r\n In [2]: source = echoip.sources.SimpleIPSource('http://curlmyip.com/')\r\n In [3]: source.ip\r\n Out[3]: IPv4Address('67.171.19.153')\r\n\r\nThe info attribute on this IPSource type is always empty.\r\n\r\nJSONIPSource\r\n~~~~~~~~~~~~\r\n\r\nThe JSONIPSource handles sites like ip-api.com that provide a more\r\ncomplete API (obviousely a JSON API). The class takes a json key to\r\nselect the IP and then uses the same validation as the SimpleIPSource\r\nclass. All other results returned by the API are boxed into a dict that\r\nis returned by the info attribute.\r\n\r\n::\r\n\r\n In [1]: import echoip.sources\r\n In [2]: source = echoip.sources.JSONIPSource('http://ip-api.com/json', 'query')\r\n In [3]: source.ip\r\n Out[3]: IPv4Address('67.171.19.153')\r\n In [4]: source.info\r\n Out[4]:\r\n {u'city': u'Keb',\r\n u'country': u'CO',\r\n u'loc': u'27.6355,-22.3235'}\r\n\r\nIPSourceFactory\r\n~~~~~~~~~~~~~~~\r\n\r\nThe IPSourceFactory is a utility class that has two purposes. One, it\r\nallows the user to create instances based on their own resources using\r\nthe provided source types. Two, it allows the user to instantiate with\r\nall of the built-in sites.\r\n\r\nInstantiating with custom resources:\r\n\r\n::\r\n\r\n In [1]: import echoip.sources\r\n In [2]: fac = echoip.sources.IPSourceFactory(use_builtins=False)\r\n In [3]: fac.add_source(echoip.sources.SimpleIPSource, 'http://10.0.0.1')\r\n In [4]: fac.add_source(echoip.sources.JSONIPSource, 'http://10.0.0.2', 'ip')\r\n In [5]: fac.num_sources\r\n Out[5]: 2\r\n In [6]: [ src for src in fac.get_sources() ]\r\n Out[6]:\r\n [,\r\n ]\r\n\r\nInstantiation with built-ins (default):\r\n\r\n::\r\n\r\n In [1]: import echoip.sources\r\n In [2]: fac = echoip.sources.IPSourceFactory()\r\n In [3]: fac.num_sources\r\n Out[3]: 14\r\n In [4]: [ src for src in fac.get_sources() ]\r\n Out[4]:\r\n [,\r\n ,\r\n ,\r\n ...\r\n ]\r\n\r\nBuilt-in Sources\r\n----------------\r\n\r\nUsers of this library who choose to use the default sources are subject\r\nto the terms and limitations of those sources and are responsible for\r\ntheir conduct when using these services.\r\n\r\n\r\nPyEchoIP Thanks\r\n---------------\r\n\r\nThis library is of my own creation. However in order to make it\r\nimmediately useful to its users, I have included in the code several\r\n'default' providers that are well known and publicly available on the\r\ninternet.\r\n\r\nThese services come in various forms, some providing detailed GEOIP\r\ninformation and some providing simple IPv4 information. I've attempted\r\nto provide sources whose usage terms do not prohibit inclusion or who do\r\nnot provide such terms. I have contacted the maintainers of these APIs\r\nvia contact instruction on each website or via whois to ask for\r\npermission.\r\n\r\nI have also attempted to create a library that will not abuse providers.\r\n\r\nIf you are a provider and would like to be removed from inclusion,\r\nplease file a github issue.\r\n\r\nSources providing free and pro versions\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\n(If you need further RPS, SSL connection or would like to contribute\r\ncash, get a license) \r\n\r\n- ip-api.com \r\n- ipinfo.io\r\n\r\nSources providing free APIs\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\n- curlmyip.com Carl Humphrey (carl@carlhumphrey.com)\r\n- wtfismyip.com by Clint Ruoho (support@wtfismyip.com)\r\n- eth0.me by Stephen Wood\r\n- httpbin.org by Runscope\r\n- l2.io", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/eflee/pyechoip", "keywords": "ip,network,api", "license": "Apache", "maintainer": "", "maintainer_email": "", "name": "pyechoip", "package_url": "https://pypi.org/project/pyechoip/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/pyechoip/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/eflee/pyechoip" }, "release_url": "https://pypi.org/project/pyechoip/1.3/", "requires_dist": null, "requires_python": null, "summary": "A generic library for getting your externally visible IP address in python.", "version": "1.3" }, "last_serial": 1556046, "releases": { "1.1": [ { "comment_text": "", "digests": { "md5": "260a27e742a393708b72eab86bbfdb83", "sha256": "6411f789026ec00ea72fbe3aee771e06ccafc53d8a82832c0bf31ec1aecbec55" }, "downloads": -1, "filename": "pyechoip-1.1.tar.gz", "has_sig": false, "md5_digest": "260a27e742a393708b72eab86bbfdb83", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8385, "upload_time": "2015-05-20T22:39:53", "url": "https://files.pythonhosted.org/packages/76/3c/f75cf4df9381c13bf93b6d0e9fb72ac65fb08583632b669a26373f56c599/pyechoip-1.1.tar.gz" } ], "1.2": [ { "comment_text": "", "digests": { "md5": "3cbf9ab8cd4e06fe59717bcb55ec7b02", "sha256": "2f8012e6e31a593860bd06c8e84eae6846f1ef37757cb7dd650de3c660fa1eb6" }, "downloads": -1, "filename": "pyechoip-1.2.tar.gz", "has_sig": false, "md5_digest": "3cbf9ab8cd4e06fe59717bcb55ec7b02", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6871, "upload_time": "2015-05-21T03:51:45", "url": "https://files.pythonhosted.org/packages/1e/1a/6e14910aec5419c639f096295db7a6c26c6b16fb053618d2461ab795d175/pyechoip-1.2.tar.gz" } ], "1.3": [ { "comment_text": "", "digests": { "md5": "24fecf822321a48a2ccf545705fc85b2", "sha256": "cb78edb55fe82ccaa36e9eeb48f49eeed97b945d532aa15a50ce4bd1e1adde67" }, "downloads": -1, "filename": "pyechoip-1.3-py2.7.egg", "has_sig": false, "md5_digest": "24fecf822321a48a2ccf545705fc85b2", "packagetype": "bdist_egg", "python_version": "2.7", "requires_python": null, "size": 13765, "upload_time": "2015-05-21T06:51:07", "url": "https://files.pythonhosted.org/packages/09/9f/154cdd9a889c72a166b417c260c6aa4f6f0dec1885769d2b525185a1e5ed/pyechoip-1.3-py2.7.egg" }, { "comment_text": "", "digests": { "md5": "672b7e25507c279e617676afddb8dc4e", "sha256": "afb8d15520b3282263c5f7f252484a7ff5f598dd03266b069e429d85b4248894" }, "downloads": -1, "filename": "pyechoip-1.3-py3.4.egg", "has_sig": false, "md5_digest": "672b7e25507c279e617676afddb8dc4e", "packagetype": "bdist_egg", "python_version": "3.4", "requires_python": null, "size": 14159, "upload_time": "2015-05-21T06:50:35", "url": "https://files.pythonhosted.org/packages/75/b6/a30794133f81dbd58e311bc854755f6a7a01af61e9d3c7ce384bc8b8158c/pyechoip-1.3-py3.4.egg" }, { "comment_text": "", "digests": { "md5": "2bb958a53fb95370da50de7817ac1ae7", "sha256": "ba7841e597b3fe0ea5f7c798693d49bc097b37b9b23765452e1c8a435af0b8c1" }, "downloads": -1, "filename": "pyechoip-1.3.tar.gz", "has_sig": false, "md5_digest": "2bb958a53fb95370da50de7817ac1ae7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9545, "upload_time": "2015-05-21T06:50:31", "url": "https://files.pythonhosted.org/packages/e4/c2/d5413cf9a1536261baf1b2e24e162c832dece030b9bb696b2f16aa7f5a63/pyechoip-1.3.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "24fecf822321a48a2ccf545705fc85b2", "sha256": "cb78edb55fe82ccaa36e9eeb48f49eeed97b945d532aa15a50ce4bd1e1adde67" }, "downloads": -1, "filename": "pyechoip-1.3-py2.7.egg", "has_sig": false, "md5_digest": "24fecf822321a48a2ccf545705fc85b2", "packagetype": "bdist_egg", "python_version": "2.7", "requires_python": null, "size": 13765, "upload_time": "2015-05-21T06:51:07", "url": "https://files.pythonhosted.org/packages/09/9f/154cdd9a889c72a166b417c260c6aa4f6f0dec1885769d2b525185a1e5ed/pyechoip-1.3-py2.7.egg" }, { "comment_text": "", "digests": { "md5": "672b7e25507c279e617676afddb8dc4e", "sha256": "afb8d15520b3282263c5f7f252484a7ff5f598dd03266b069e429d85b4248894" }, "downloads": -1, "filename": "pyechoip-1.3-py3.4.egg", "has_sig": false, "md5_digest": "672b7e25507c279e617676afddb8dc4e", "packagetype": "bdist_egg", "python_version": "3.4", "requires_python": null, "size": 14159, "upload_time": "2015-05-21T06:50:35", "url": "https://files.pythonhosted.org/packages/75/b6/a30794133f81dbd58e311bc854755f6a7a01af61e9d3c7ce384bc8b8158c/pyechoip-1.3-py3.4.egg" }, { "comment_text": "", "digests": { "md5": "2bb958a53fb95370da50de7817ac1ae7", "sha256": "ba7841e597b3fe0ea5f7c798693d49bc097b37b9b23765452e1c8a435af0b8c1" }, "downloads": -1, "filename": "pyechoip-1.3.tar.gz", "has_sig": false, "md5_digest": "2bb958a53fb95370da50de7817ac1ae7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9545, "upload_time": "2015-05-21T06:50:31", "url": "https://files.pythonhosted.org/packages/e4/c2/d5413cf9a1536261baf1b2e24e162c832dece030b9bb696b2f16aa7f5a63/pyechoip-1.3.tar.gz" } ] }