# python-ifconfig-me
## Project Overview
This is a simple Python library to detect the current public IP of your machine.
## Getting Started
### Prerequisites
Python version >= 3.9
### Installation
```bash
pip install python-ifconfig-me
```
## Usage
### Basic usage - Use as a tool
Show help messages:
```python
$ ifconfig-me -h
```
Show the current public ip:
```python
$ ifconfig-me
```
Show statistics used to determine the public IP.
```python
$ ifconfig-me --show-statistics
{
"ip": "xxx.xxx.xxx.xxx",
"statistics": [
{
"ipObject": {
"ip": "xxx.xxx.xxx.xxx"
},
"weight": 4,
"priority": 0,
"retrievers": [
{
"url": "https://ifconfig.me/ip",
"priority": 0
},
{
"url": "https://ipecho.net/plain",
"priority": 0
},
{
"url": "https://ipinfo.io/ip",
"priority": 0
},
{
"url": "https://httpbin.org/ip",
"priority": 0
}
]
},
{
"ipObject": {
"ip": "xxx.xxx.xxx.xxx\n"
},
"weight": 3,
"priority": 0,
"retrievers": [
{
"url": "https://checkip.amazonaws.com",
"priority": 0
},
{
"url": "https://icanhazip.com",
"priority": 0
},
{
"url": "https://ifconfig.co/ip",
"priority": 0
}
]
}
]
}
xxx.xxx.xxx.xxx
```
Force to return IPv4
```
$ ifconfig-me --ipv4
```
Force to return IPv6
```
$ ifconfig-me --ipv6
```
Prefer ipv4 over ipv6. By default, if an IPv4 address and IPv6 address are both detected and have the same weight (i.e. the same number of services detected them), the IPv4 address is returned. This option forces the IPv6 address to be returned in this case.
Note: This option only takes effect when both an IPv4 address and an IPv6 address have the same weight.
```
$ ifconfig-me --prefer-ipv6
```
Use `--logLevel` to set the log level. The default log level is `ERROR`.
### Advanced usage - Use as a library
#### getPublicIPAsync and getPulicIP
There are two versions of the getPublicIP function: synchronous and asynchronous.
Async version:
```python
import asyncio
from python_ifconfig_me import getPublicIPAsync
asyncio.run(getPublicIPAsync())
```
Sync version:
```python
from python_ifconfig_me import getPublicIP
public = getPublicIP()
```
The sync version is just a wrapper of the async version. If possible, use the async version because it is more efficient.
```python
import asyncio
from python_ifconfig_me import getPublicIPAsync, GetPublicIPOptions
options = GetPublicIPOptions(
return_statistics=True
)
asyncio.run(getPublicIPAsync(options))
```
#### Use retrievers
You can pass retrievers to the `getPublicIPAsync/getPublicIP` function. A retriever follows the `IPRetriever` protocol. You can implement your own retriever by inheriting the `IPRetriever` class.
```python
import asyncio
from python_ifconfig_me import getPublicIPAsync, GetPublicIPOptions
from python_ifconfig_me.core.ipretriever.simpleTextIPRetriever import SimpleTextIPRetriever
options = GetPublicIPOptions(
return_statistics=True
)
retrievers = [
SimpleTextIPRetriever("https://ifconfig.me/ip"),
]
asyncio.run(getPublicIPAsync(options, retrievers))
```
If you want to add your retriever to the default retrievers, you can use the `DEFAULT_IP_RETRIEVERS` variable.
```python
import asyncio
from python_ifconfig_me import getPublicIPAsync, GetPublicIPOptions
from python_ifconfig_me.core.ipretriever.simpleTextIPRetriever import SimpleTextIPRetriever
from python_ifconfig_me.core.ipretriever import DEFAULT_IP_RETRIEVERS
options = GetPublicIPOptions(
return_statistics=True
)
retrievers = DEFAULT_IP_RETRIEVERS + [
SimpleTextIPRetriever("https://ifconfig.me/ip"),
]
asyncio.run(getPublicIPAsync(options, retrievers))
```
## How this project works
The idea behind this library is pretty simple: majority voting among multiple third-party public ip detection services.
As of now, the following services are configured to be used for detention:
- https://checkip.amazonaws.com
- https://icanhazip.com
- https://ifconfig.co/ip
- https://ifconfig.me/ip
- https://ipecho.net/plain
- https://ipinfo.io/ip
- https://httpbin.org/ip
- https://api.ipify.org
## LICENSE
The project is licensed under the GPL license. For more information, please refer to the [LICENSE](./LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/catwang01/python-ifconfig-me",
"name": "python-ifconfig-me",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "ifconfig, ip, public ip, python, network, ipv4, ipv6",
"author": "catwang01",
"author_email": "edwardelricwzx@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9a/bf/6752ec12bb4e7e4b7d6574b257dd9829dcfe388b0241252a92eb982a2435/python_ifconfig_me-0.0.2.tar.gz",
"platform": null,
"description": "# python-ifconfig-me\n\n\n\n## Project Overview\n\nThis is a simple Python library to detect the current public IP of your machine.\n\n## Getting Started\n\n### Prerequisites\n\nPython version >= 3.9\n\n### Installation\n\n```bash\npip install python-ifconfig-me\n```\n\n## Usage\n\n### Basic usage - Use as a tool\n\nShow help messages:\n\n```python\n$ ifconfig-me -h\n```\n\nShow the current public ip:\n\n```python\n$ ifconfig-me\n```\n\nShow statistics used to determine the public IP.\n\n```python\n$ ifconfig-me --show-statistics\n{\n \"ip\": \"xxx.xxx.xxx.xxx\",\n \"statistics\": [\n {\n \"ipObject\": {\n \"ip\": \"xxx.xxx.xxx.xxx\"\n },\n \"weight\": 4,\n \"priority\": 0,\n \"retrievers\": [\n {\n \"url\": \"https://ifconfig.me/ip\",\n \"priority\": 0\n },\n {\n \"url\": \"https://ipecho.net/plain\",\n \"priority\": 0\n },\n {\n \"url\": \"https://ipinfo.io/ip\",\n \"priority\": 0\n },\n {\n \"url\": \"https://httpbin.org/ip\",\n \"priority\": 0\n }\n ]\n },\n {\n \"ipObject\": {\n \"ip\": \"xxx.xxx.xxx.xxx\\n\"\n },\n \"weight\": 3,\n \"priority\": 0,\n \"retrievers\": [\n {\n \"url\": \"https://checkip.amazonaws.com\",\n \"priority\": 0\n },\n {\n \"url\": \"https://icanhazip.com\",\n \"priority\": 0\n },\n {\n \"url\": \"https://ifconfig.co/ip\",\n \"priority\": 0\n }\n ]\n }\n ]\n}\nxxx.xxx.xxx.xxx\n```\n\nForce to return IPv4\n\n```\n$ ifconfig-me --ipv4\n```\n\nForce to return IPv6\n\n```\n$ ifconfig-me --ipv6\n```\n\nPrefer ipv4 over ipv6. By default, if an IPv4 address and IPv6 address are both detected and have the same weight (i.e. the same number of services detected them), the IPv4 address is returned. This option forces the IPv6 address to be returned in this case.\n\nNote: This option only takes effect when both an IPv4 address and an IPv6 address have the same weight.\n\n```\n$ ifconfig-me --prefer-ipv6\n```\n\nUse `--logLevel` to set the log level. The default log level is `ERROR`.\n\n### Advanced usage - Use as a library\n\n#### getPublicIPAsync and getPulicIP\n\nThere are two versions of the getPublicIP function: synchronous and asynchronous.\n\nAsync version:\n\n```python\nimport asyncio\nfrom python_ifconfig_me import getPublicIPAsync\n\nasyncio.run(getPublicIPAsync())\n```\n\nSync version:\n\n```python\nfrom python_ifconfig_me import getPublicIP\n\npublic = getPublicIP()\n```\n\nThe sync version is just a wrapper of the async version. If possible, use the async version because it is more efficient.\n\n```python\nimport asyncio\nfrom python_ifconfig_me import getPublicIPAsync, GetPublicIPOptions\n\noptions = GetPublicIPOptions(\n return_statistics=True\n)\nasyncio.run(getPublicIPAsync(options))\n```\n\n#### Use retrievers\n\nYou can pass retrievers to the `getPublicIPAsync/getPublicIP` function. A retriever follows the `IPRetriever` protocol. You can implement your own retriever by inheriting the `IPRetriever` class.\n\n```python\nimport asyncio\nfrom python_ifconfig_me import getPublicIPAsync, GetPublicIPOptions\nfrom python_ifconfig_me.core.ipretriever.simpleTextIPRetriever import SimpleTextIPRetriever\n\noptions = GetPublicIPOptions(\n return_statistics=True\n)\nretrievers = [\n SimpleTextIPRetriever(\"https://ifconfig.me/ip\"),\n]\nasyncio.run(getPublicIPAsync(options, retrievers))\n```\n\nIf you want to add your retriever to the default retrievers, you can use the `DEFAULT_IP_RETRIEVERS` variable.\n\n```python\nimport asyncio\nfrom python_ifconfig_me import getPublicIPAsync, GetPublicIPOptions\nfrom python_ifconfig_me.core.ipretriever.simpleTextIPRetriever import SimpleTextIPRetriever\nfrom python_ifconfig_me.core.ipretriever import DEFAULT_IP_RETRIEVERS\n\noptions = GetPublicIPOptions(\n return_statistics=True\n)\nretrievers = DEFAULT_IP_RETRIEVERS + [\n SimpleTextIPRetriever(\"https://ifconfig.me/ip\"),\n]\nasyncio.run(getPublicIPAsync(options, retrievers))\n```\n\n## How this project works\n\nThe idea behind this library is pretty simple: majority voting among multiple third-party public ip detection services.\n\nAs of now, the following services are configured to be used for detention:\n\n- https://checkip.amazonaws.com\n- https://icanhazip.com\n- https://ifconfig.co/ip\n- https://ifconfig.me/ip\n- https://ipecho.net/plain\n- https://ipinfo.io/ip\n- https://httpbin.org/ip\n- https://api.ipify.org\n\n\n## LICENSE\n\nThe project is licensed under the GPL license. For more information, please refer to the [LICENSE](./LICENSE) file.\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "This is a tool to get public ip of your machine",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/catwang01/python-ifconfig-me",
"Repository": "https://github.com/catwang01/python-ifconfig-me"
},
"split_keywords": [
"ifconfig",
" ip",
" public ip",
" python",
" network",
" ipv4",
" ipv6"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "92f50d3a7aa4ebfcf5e0bae53ca944b72ce4d420179456b676f44446c5ee30b8",
"md5": "1d255e74105030e5913c1de4e2ce7e46",
"sha256": "2ca2e7d9e7433027c3c8c19221980483768f181f8caa8eedb463425dc87fdd07"
},
"downloads": -1,
"filename": "python_ifconfig_me-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d255e74105030e5913c1de4e2ce7e46",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 23413,
"upload_time": "2024-12-16T13:04:16",
"upload_time_iso_8601": "2024-12-16T13:04:16.807742Z",
"url": "https://files.pythonhosted.org/packages/92/f5/0d3a7aa4ebfcf5e0bae53ca944b72ce4d420179456b676f44446c5ee30b8/python_ifconfig_me-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9abf6752ec12bb4e7e4b7d6574b257dd9829dcfe388b0241252a92eb982a2435",
"md5": "876ae5fe4dac3aa63fd320ebe61fc61d",
"sha256": "d4bc3291d0ab366afd28cde4602f71dd011f8d38fb6d50163ee2baa17b06fc9a"
},
"downloads": -1,
"filename": "python_ifconfig_me-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "876ae5fe4dac3aa63fd320ebe61fc61d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 20221,
"upload_time": "2024-12-16T13:04:18",
"upload_time_iso_8601": "2024-12-16T13:04:18.344206Z",
"url": "https://files.pythonhosted.org/packages/9a/bf/6752ec12bb4e7e4b7d6574b257dd9829dcfe388b0241252a92eb982a2435/python_ifconfig_me-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 13:04:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "catwang01",
"github_project": "python-ifconfig-me",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "python-ifconfig-me"
}
JSON
