# Python FreeDNS Client
[](https://pypi.org/project/freedns-client/)
This is a Python wrapper for [FreeDNS.afraid.org](https://freedns.afraid.org), which allows for the free registration of subdomains.
## Features:
- Login with existing account
- Send account creation email
- Get domains in the registry
- Get subdomains in an account
- Create a new subdomain record
- Update subdomain records
## Installation:
You can install this library using the following command:
```
pip3 install freedns-client
```
## Documentation:
### Using the Client:
The `freedns.Client` object does not take any arguments.
```python
import freedns
client = freedns.Client()
```
### Request a Captcha:
Whenever a captcha is needed, you can request it from the server using `client.get_captcha`. It accepts no arguments, and returns the bytes of a PNG image containing the captcha.
### Logging In:
You can log into an existing account with the `client.login` function. It takes the following arguments:
- `username` - The username/email of the account to log into.
- `password` - The password of the account.
If the login fails, the library will raise a `RuntimeError` with the error message reported by FreeDNS.
### Signing Up (Captcha Required):
You can send an activation email using `client.create_account`, which accepts the following arguments:
- `captcha_code` - The solution for the last captcha requested.
- `firstname` - The first name associated with the account.
- `lastname` - The last name associated with the account.
- `username` - The new account's username.
- `password` - The new account's password.
- `email` - The email used for login and verification.
After recieving the activation email, you can run `client.activate_account`, which accepts the following arugments:
- `activation_code` - The activation code that you recieved in your email. This should be the random string of letters at the end of the activation URL. For example, `klsEii2txkW7Wa9DgGaaG6s8` would be the activation code for this URL: `http://freedns.afraid.org/signup/activate.php?klsEii2txkW7Wa9DgGaaG6s8`
### Fetching the Domain Registry:
You can query the public domain registry using `client.get_registry`. It accepts the following optional arguments:
- `page = 1` - Which page of results to start at.
- `sort = 5` - The sort mode to use (details below).
- `query = None` - The search query to use.
**Sort modes:**
1. Domain Name
2. Status, Age
3. Domain Owner
4. Age
5. Popularity
6. Domain Length, Popularity
Any other value will default to sorting by popularity.
The function returns a dictionary consisting of some metadata, as well as a list of domains.
```python
>> client.get_registry()
>>> client.get_registry(page=10)
{'domains_info': {'page_start': 901, 'page_end': 1000, 'total': 32715}, 'pages_info': {'current_page': 11, 'total_pages': 328}, 'domains': [{'domain': 'zipper-maker.com', 'id': 167443, 'hosts': 139, 'status': 'public', 'owner_name': 'mwong', 'owner_id': 53163, 'age': 6045, 'created': '03/11/2007'}, ...]}
```
### List Subdomains in an Account (Auth Needed):
You can list the subdomains registered to your account using `client.get_subdomains`. The function takes no arguments.
```python
>> client.get_subdomains()
[{'subdomain': 'randomdomain.hs.vc', 'id': '34523523', 'type': 'CNAME', 'destination': 'example.com'}, ...]
```
This function returns a list of dictionaries representing each subdomain.
### Get a Subdomain's Details (Auth Needed):
To get the details for a specific subdomain, use `client.get_subdomain_details`. The function takes the following arguments:
- `subdomain_id` - The ID of the subdomain you are querying. You can find this with `client.get_subdomains`.
The function will return a dict with the subdomain details.
```python
>> client.get_subdomain_details(20123422)
{'type': 'A', 'subdomain': 'subdomain', 'domain': 'example.com', 'domain_id': 435322, 'destination': '1.1.1.1', 'wildcard': False}
```
### Register a New Subdomain (Auth+Captcha Needed):
Use the `client.create_subdomain` function to register a new subdomain. The function accepts the following arguments:
- `captcha_code` - The solution for the last captcha requested.
- `record_type` - The type of record to create (for example `CNAME` or `A`).
- `subdomain` - The subdomain to create (does not include the domain name).
- `domain_id` - The ID of the domain to use. You can get this with `client.get_registry`, as documented earlier.
- `destination` - The destination for the record.
The function will not return anything on success, but it'll raise a `RuntimeError` if the subdomain creation has failed.
### Update a Subdomain (Auth+Captcha Needed):
Use the `client.update_subdomain` function to update an existing subdomain. The function accepts the following arguments:
- `subdomain_id` - The ID of the subdomain to modify.
- `captcha_code` - The solution for the last captcha requested.
- `record_type = None` - The record type.
- `subdomain = None` - The subdomain to use.
- `domain_id = None` - The ID of the domain to use.
- `destination = None` - The destination for the record.
If you don't supply one of the optional arguments, then the value won't change. If the operation fails, a `RuntimeError` will be raised.
## Copyright:
This program is licensed under the [GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.txt). All code has been written by me, [ading2210](https://github.com/ading2210).
### Copyright Notice:
```
ading2210/freedns-client: a Python API wrapper for FreeDNS.afraid.org
Copyright (C) 2023 ading2210
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ading2210/freedns-client",
"name": "freedns-client",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "ading2210",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# Python FreeDNS Client\n\n[](https://pypi.org/project/freedns-client/)\n\nThis is a Python wrapper for [FreeDNS.afraid.org](https://freedns.afraid.org), which allows for the free registration of subdomains.\n\n## Features:\n- Login with existing account\n- Send account creation email\n- Get domains in the registry\n- Get subdomains in an account\n- Create a new subdomain record\n- Update subdomain records\n\n## Installation:\nYou can install this library using the following command: \n```\npip3 install freedns-client\n```\n\n## Documentation:\n\n### Using the Client:\nThe `freedns.Client` object does not take any arguments.\n\n```python\nimport freedns\nclient = freedns.Client()\n```\n\n### Request a Captcha:\nWhenever a captcha is needed, you can request it from the server using `client.get_captcha`. It accepts no arguments, and returns the bytes of a PNG image containing the captcha.\n\n### Logging In:\nYou can log into an existing account with the `client.login` function. It takes the following arguments:\n- `username` - The username/email of the account to log into.\n- `password` - The password of the account.\n\nIf the login fails, the library will raise a `RuntimeError` with the error message reported by FreeDNS.\n\n### Signing Up (Captcha Required):\nYou can send an activation email using `client.create_account`, which accepts the following arguments:\n- `captcha_code` - The solution for the last captcha requested.\n- `firstname` - The first name associated with the account.\n- `lastname` - The last name associated with the account.\n- `username` - The new account's username.\n- `password` - The new account's password. \n- `email` - The email used for login and verification.\n\nAfter recieving the activation email, you can run `client.activate_account`, which accepts the following arugments:\n- `activation_code` - The activation code that you recieved in your email. This should be the random string of letters at the end of the activation URL. For example, `klsEii2txkW7Wa9DgGaaG6s8` would be the activation code for this URL: `http://freedns.afraid.org/signup/activate.php?klsEii2txkW7Wa9DgGaaG6s8` \n\n### Fetching the Domain Registry:\nYou can query the public domain registry using `client.get_registry`. It accepts the following optional arguments:\n- `page = 1` - Which page of results to start at.\n- `sort = 5` - The sort mode to use (details below).\n- `query = None` - The search query to use.\n\n**Sort modes:**\n1. Domain Name\n2. Status, Age\n3. Domain Owner\n4. Age\n5. Popularity\n6. Domain Length, Popularity\n\nAny other value will default to sorting by popularity.\n\nThe function returns a dictionary consisting of some metadata, as well as a list of domains.\n\n```python\n>> client.get_registry()\n>>> client.get_registry(page=10)\n{'domains_info': {'page_start': 901, 'page_end': 1000, 'total': 32715}, 'pages_info': {'current_page': 11, 'total_pages': 328}, 'domains': [{'domain': 'zipper-maker.com', 'id': 167443, 'hosts': 139, 'status': 'public', 'owner_name': 'mwong', 'owner_id': 53163, 'age': 6045, 'created': '03/11/2007'}, ...]}\n```\n\n### List Subdomains in an Account (Auth Needed):\nYou can list the subdomains registered to your account using `client.get_subdomains`. The function takes no arguments.\n\n```python\n>> client.get_subdomains()\n[{'subdomain': 'randomdomain.hs.vc', 'id': '34523523', 'type': 'CNAME', 'destination': 'example.com'}, ...]\n```\n\nThis function returns a list of dictionaries representing each subdomain.\n\n### Get a Subdomain's Details (Auth Needed):\nTo get the details for a specific subdomain, use `client.get_subdomain_details`. The function takes the following arguments:\n- `subdomain_id` - The ID of the subdomain you are querying. You can find this with `client.get_subdomains`.\n\nThe function will return a dict with the subdomain details.\n\n```python\n>> client.get_subdomain_details(20123422)\n{'type': 'A', 'subdomain': 'subdomain', 'domain': 'example.com', 'domain_id': 435322, 'destination': '1.1.1.1', 'wildcard': False}\n```\n\n### Register a New Subdomain (Auth+Captcha Needed):\nUse the `client.create_subdomain` function to register a new subdomain. The function accepts the following arguments:\n- `captcha_code` - The solution for the last captcha requested.\n- `record_type` - The type of record to create (for example `CNAME` or `A`).\n- `subdomain` - The subdomain to create (does not include the domain name).\n- `domain_id` - The ID of the domain to use. You can get this with `client.get_registry`, as documented earlier.\n- `destination` - The destination for the record. \n\nThe function will not return anything on success, but it'll raise a `RuntimeError` if the subdomain creation has failed.\n\n### Update a Subdomain (Auth+Captcha Needed):\nUse the `client.update_subdomain` function to update an existing subdomain. The function accepts the following arguments:\n- `subdomain_id` - The ID of the subdomain to modify.\n- `captcha_code` - The solution for the last captcha requested.\n- `record_type = None` - The record type.\n- `subdomain = None` - The subdomain to use.\n- `domain_id = None` - The ID of the domain to use. \n- `destination = None` - The destination for the record. \n\nIf you don't supply one of the optional arguments, then the value won't change. If the operation fails, a `RuntimeError` will be raised.\n\n## Copyright: \nThis program is licensed under the [GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.txt). All code has been written by me, [ading2210](https://github.com/ading2210).\n\n### Copyright Notice:\n```\nading2210/freedns-client: a Python API wrapper for FreeDNS.afraid.org\nCopyright (C) 2023 ading2210\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see <https://www.gnu.org/licenses/>.\n```\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A Python package for interacting with FreeDNS.afraid.org",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/ading2210/freedns-client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0766bc761cbf0e4f9e18b5dc28365ed35a0d391b0421c184e81926dbddf067a6",
"md5": "6994c69ba04df0cd62904609ae8392cf",
"sha256": "b8bae10526762f78cff56eed83a63969e02fdd6dbc324ea49aa0eb11189495d9"
},
"downloads": -1,
"filename": "freedns_client-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6994c69ba04df0cd62904609ae8392cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18682,
"upload_time": "2023-10-13T22:52:57",
"upload_time_iso_8601": "2023-10-13T22:52:57.419801Z",
"url": "https://files.pythonhosted.org/packages/07/66/bc761cbf0e4f9e18b5dc28365ed35a0d391b0421c184e81926dbddf067a6/freedns_client-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-13 22:52:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ading2210",
"github_project": "freedns-client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "freedns-client"
}
JSON
