{"id":15374593,"url":"https://github.com/ading2210/freedns-client","last_synced_at":"2025-04-15T15:11:36.286Z","repository":{"id":193820015,"uuid":"689538179","full_name":"ading2210/freedns-client","owner":"ading2210","description":"A Python API wrapper for FreeDNS.afraid.org","archived":false,"fork":false,"pushed_at":"2023-10-13T22:50:17.000Z","size":37,"stargazers_count":12,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-28T21:41:58.637Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ading2210.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-09-10T05:58:01.000Z","updated_at":"2025-03-16T17:01:37.000Z","dependencies_parsed_at":"2023-09-10T08:40:32.659Z","dependency_job_id":null,"html_url":"https://github.com/ading2210/freedns-client","commit_stats":null,"previous_names":["ading2210/freedns-client"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ading2210%2Ffreedns-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ading2210%2Ffreedns-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ading2210%2Ffreedns-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ading2210%2Ffreedns-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ading2210","download_url":"https://codeload.github.com/ading2210/freedns-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249094932,"owners_count":21211837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T13:59:06.950Z","updated_at":"2025-04-15T15:11:36.250Z","avatar_url":"https://github.com/ading2210.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python FreeDNS Client\n\n[![PyPi Version](https://img.shields.io/pypi/v/freedns-client.svg)](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\u003e\u003e client.get_registry()\n\u003e\u003e\u003e 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\u003e\u003e 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\u003e\u003e 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 \u003chttps://www.gnu.org/licenses/\u003e.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fading2210%2Ffreedns-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fading2210%2Ffreedns-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fading2210%2Ffreedns-client/lists"}