0.1.0 - Major overhaul - methods return dataclasses, caching, new met…

…hods + more - Moved the code into a Python module `namecheap/` instead of a flat `namecheap.py` file. - Exceptions moved to `namecheap/exceptions.py` - Helper functions moved to `namecheap/helpers.py` - Dataclasses for representing objects returned by the API are stored in `namecheap/objects.py` - Main `Api` class and related variables / private functions moved to `namecheap/namecheap.py` - Completely overhauled almost every method - API call methods now return dataclasses using the classes defined in `namecheap/objects.py` - Added support for more APIs - Added API `namecheap.domains.getInfo` as `domains_getInfo` and `get_domain_info` - Added API `namecheap.domains.renew` as `domains_renew` and `renew_domain` - Added API `namecheap.users.getPricing` as `users_getPricing`, with wrapper method `get_tld_prices` and `get_all_tld_prices` for simpler querying of specifically domain TLD prices - Added API `namecheap.domains.gettldlist` as `domains_getTldList` for retrieving available TLDs - Added API `namecheap.domains.dns.setDefault` as `domains_dns_setDefault` for resetting a domain back to the default Namecheap DNS - Probably more APIs which were added, but weren't clear in the diff - Added `set_endpoint` to allow users to override the `ENDPOINTS`, e.g. for proxy domains to assist with namecheap's IP whitelisting on a private network - Changed `domains_check` to return the actual data from `domains.check` - availability checking with boolean results has now been moved to `domains_available` - Changed dirty `print()` statements into `log.debug()` - `debug=True` now simple creates a console logger with DEBUG level. - Added `py36` extra to `setup.py` - which is just an alias to the `dataclasses` backport package / shim - required to use `privex-namecheap` on Python 3.6.x - Added `namecheap-api-cli` to `scripts` in setup.py - so that the CLI tool gets installed into ~/.local/bin or /usr/local/bin/ - Updated package name to `privex_namecheap` (privex-namecheap on pypi), as well as the URL, author, email, description etc. - And **much much more**. If you care enough to find out the nitty gritty changes, read the Git code diff.
Privex · Sep 2, 2020 · 2c512b3 · 2c512b3
1 parent 8ca9f2b
commit 2c512b3
Show file tree

Hide file tree

Showing 14 changed files with 2,311 additions and 748 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 env
 credentials.py
+credentials_*.py
 .DS_Store
 
 *.py[cod]

diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,8 +1,40 @@
++===================================================================+
+| © 2020 Privex Inc. |
+| https://www.privex.io |
++===================================================================+
+| |
+| Python Namecheap API |
+| |
+| Repo: https://github.com/Privex/PyNamecheap |
+| PyPi Package: privex-namecheap |
+| |
+| License: X11 / MIT |
+| |
+| Core Developer(s): |
+| |
+| (+) Chris (@someguy123) [Privex] |
+| (+) Kale (@kryogenic) [Privex] |
+| |
++===================================================================+
+
+Copyright 2020 Privex Inc. ( https://www.privex.io )
+Copyright (c) 2016-2020 Bemmu Sepponen
+
 The MIT License (MIT)
-Copyright (c) 2016 Bemmu Sepponen
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -12,13 +12,64 @@ This client supports:
 - Setting DNS info to default values
 - Set DNS host records
 
+**NOTE: This is a fork of [Bemmu/PyNamecheap](https://github.com/Bemmu/PyNamecheap)**.
+
+The original library was created by @Bemmu - we (@Privex) forked the library so that we
+could make various major changes, including using features which **prevent backwards compatibility**
+**with Python 2.x and anything before 3.6**.
+
+If you absolutely need to use a Python version prior to 3.6.0, then you should use the original
+package: [Bemmu/PyNamecheap](https://github.com/Bemmu/PyNamecheap) 
+
 ### Installation
 
-Thanks to @inomoz, as simple as:
+First, check your Python version by running `python3 -V`
 
 ```
-pip install PyNamecheap
+user@host ~ $ python3 -V
+Python 3.8.3
+```
+
+#### For Python 3.7 and higher
+
+To install our fork's (`Privex/PyNamecheap`) python package - use `pip3` or `pipenv`
+and install the package name `privex-namecheap` 
+
 ```
+# Using standard Pip
+pip3 install -U privex-namecheap
+
+# Using Pipenv
+pipenv install privex-namecheap
+
+```
+
+#### For Python 3.6.x
+
+**If you are running Python 3.6.x**, you'll need to install our package with the `py36` extra - or
+manually install the `dataclasses` package.
+
+```
+# Using standard Pip
+pip3 install -U 'privex-namecheap[py36]'
+
+# Using Pipenv
+pipenv install 'privex-namecheap[py36]'
+```
+
+Do **NOT** install `privex-namecheap[py36]` if you are running Python 3.7 or newer. It will break your
+built-in Python `dataclasses` module.
+
+#### For Python 3.5.x or older...
+
+The original library was created by @Bemmu - we (@Privex) forked the library so that we
+could make various major changes, including using features which **prevent backwards compatibility**
+**with Python 2.x and anything before 3.6**.
+
+This means it's not possible to use `privex-namecheap` with any Python version older than `3.6.0`
+
+If you absolutely need to use a Python version prior to 3.6.0, then you should use the original
+package: [Bemmu/PyNamecheap](https://github.com/Bemmu/PyNamecheap) 
 
 ### How to sign up to start using the API
 
@@ -40,35 +91,141 @@ You'll get to your credentials page. From here you need to take note of your api
 
 Copy namecheap.py to your project. In Python you can access the API as follows:
 
- from namecheap import Api
- api = Api(username, api_key, username, ip_address, sandbox = True)
+```python
+from namecheap import Api
+# api_username, api_key, client_ip_address
+api = Api('NamecheapUsername', 'YourNamecheapAPIKey', '12.34.56.78', sandbox=True, debug=True)
 
-The fields are the ones which appear in the credentials screen above. The username appears twice, because you might be acting on behalf of someone else.
+# Using keyword arguments (recommended - more reliable in the event the constructor is changed)
+api = Api(
+ ApiUser='NamecheapUsername', 
+ ApiKey='YourNamecheapAPIKey',
+ ClientIP='12.34.56.78', 
 
-### Registering a domain name using the API
+ # OPTIONAL. You only need to specify UserName if you're managing resources on a different
+ # Namecheap account from your own account - e.g. someone has granted your account permission
+ # to manage their domains etc.
+ UserName='NamecheapUsername', 
 
-Unfortunately you need a bunch of contact details to register a domain, so it is not as easy as just providing the domain name. In the sandbox, the following contact details are acceptable. Trickiest field is the phone number, which has to be formatted as shown.
+ # By default, sandbox and debug are both False. Set sandbox=True to use the Namecheap Sandbox API,
+ # and set debug=True to enable verbose debug logging to help you understand what the library is
+ # doing behind the scenes.
+ sandbox=True, debug=True
+)
 
- api.domains_create(
-  DomainName = 'registeringadomainthroughtheapiwow.com',
-  FirstName = 'Jack',
-  LastName = 'Trotter',
-  Address1 = 'Ridiculously Big Mansion, Yellow Brick Road',
-  City = 'Tokushima',
-  StateProvince = 'Tokushima',
-  PostalCode = '771-0144',
-  Country = 'Japan',
-  Phone = '+81.123123123',
-  EmailAddress = 'jack.trotter@example.com'
- )
+```
+The fields are the ones which appear in the credentials screen above. 
+
+The username appears twice, because you might be acting on behalf of someone else.
+
+### Registering a domain name using the API + common usage examples
+
+Unfortunately you need a bunch of contact details to register a domain, so it is not as easy as just providing the domain name. 
+
+In the sandbox, the following contact details are acceptable. Trickiest field is the phone number, which has to be formatted as shown.
+
+```python
+from namecheap import Api, DomainRecord
+
+contact_details = dict(
+ FirstName='Jack',
+ LastName='Trotter',
+ Address1='Ridiculously Big Mansion, Yellow Brick Road',
+ City='Tokushima',
+ StateProvince='Tokushima',
+ PostalCode='771-0144',
+ Country='Japan',
+ Phone="+81.123123123",
+ EmailAddress='jack.trotter@example.com'
+)
+
+api = Api('NamecheapUsername', 'YourNamecheapAPIKey', '12.34.56.78', sandbox=True, debug=True)
+
+# First let's find out how much various TLDs cost at the moment
+tld_prices = api.get_tld_prices('com', 'org', 'net', 'bz', 'xyz', 'us')
+for tld, price in tld_prices.items():
+ print(f".{tld} pricing - Current Price: ${price.total_your_price:.2f} | Regular Price: ${price.total_regular_price:.2f}")
+print("-------------")
+"""
+(Example output)
+.com pricing - Current Price: $9.06 | Regular Price: $9.06
+.org pricing - Current Price: $13.16 | Regular Price: $13.16
+.net pricing - Current Price: $12.16 | Regular Price: $13.16
+.bz pricing - Current Price: $21.88 | Regular Price: $21.88
+.xyz pricing - Current Price: $1.18 | Regular Price: $11.06
+.us pricing - Current Price: $3.88 | Regular Price: $8.48
+-------------
+"""
+
+# Next let's specifically get just the .com TLD price
+com_price = api.get_tld_prices('com')
+print(f"Price you'll pay: ${com_price.total_your_price:.2f} | Regular Non-promo Price: ${com_price.total_regular_price:.2f}")
+
+# Now for the important part - registering the domain. We need to specify all of the contact details
+# when registering the domain.
+reg = api.domains_create(
+ 'mycooldomain.com',
+ **contact_details
+)
+print("Domain registration result:", reg)
+# domains_create is also available as the alias: register_domain
+
+# Assuming no exception occurred, then we can now setup the records for the domain
+
+# Using replace_records, we can get rid of all the default parking page records etc., and overwrite them
+# with our custom records - in one fell swoop.
+api.replace_records(
+ 'mycooldomain.com',
+ DomainRecord('A', '185.130.44.10'), # Name: @ | Type: A | Value: 185.130.44.10
+ DomainRecord('AAAA', '2a07:e00::abc'), # Name: @ | Type: A | Value: 185.130.44.10
+ DomainRecord('CNAME', 'mycooldomain.com', 'www') # Name: www | Type: CNAME | Value: mycooldomain.com
+)
+
+# Using add_record, we can insert singular records to the existing records, instead of overwriting them
+api.add_record('mycooldomain.com', 'TXT', 'hello world') # Name: @ | Type: TXT | Value: hello world
+api.add_record('mycooldomain.com', 'A', '127.0.0.1', 'test') # Name: test | Type: A | Value: 127.0.0.1
+
+# Using delete_record, we can delete individual records based on their type, content, and sub-domain
+api.delete_record('mycooldomain.com', 'TXT', 'hello world') # Delete the root domain TXT record 'hello world'
+api.delete_record('mycooldomain.com', 'A', '127.0.0.1', 'test') # Delete the 'test' subdomain A record '127.0.0.1'
+
+info = api.domains_getInfo('mycooldomain.com')
+print(info.expired_date) # Output: 2020-11-05 00:00:00
+
+# If mycooldomain.com is expiring in the next 60 days, renew it for one year.
+if info.days_until_expires < 60:
+ api.renew_domain('mycooldomain.com')
+
+# Change the nameservers for mycooldomain.com to ns1.privex.io to ns3.privex.io
+api.set_nameservers('mycooldomain.com', 'ns1.privex.io', 'ns2.privex.io', 'ns3.privex.io')
+
+# Change the nameservers for mycooldomain.com back to the default Namecheap nameservers,
+# to allow using the domain with Namecheap's email service, URL redirect records + other features.
+api.domains_dns_setDefault('mycooldomain.com')
+```
 
 This call should succeed in the sandbox, but if you use the API to check whether this domain is available after registering it, the availability will not change. This is normal.
 
 ### How to check if a domain name is available
 
-The domains_check method returns True if the domain is available.
-
- api.domains_check(domain_name)
+The `domains_available` method returns True if the domain is available.
+
+```python
+from namecheap import Api
+api = Api('NamecheapUsername', 'YourNamecheapAPIKey', '12.34.56.78', sandbox=True, debug=True)
+api.domains_available('taken.com', 'apsdjcpoaskdc.com')
+# Might result in
+# {
+# 'taken.com' : False,
+# 'apsdjcpoaskdc.com' : True
+# }
+
+# If you check a singular domain, it will return a bool, unless you pass force_dict=True
+api.domains_available('taken.com')
+# True
+api.domains_available('taken.com', force_dict=True)
+# {'taken.com' : False}
+```
 
 You can also pass a list of domain names, in which case it does a batch check for all and returns a dictionary of the answers.
 You should probably not be writing a mass domain checking tool using this, it is intended to be used before registering a domain.
@@ -97,39 +254,34 @@ Then you just call the script with desired arguments:
 
 Here's the example of simple DNS records management script:
 
- #!/usr/bin/env python
+```python
 
- """
- Define variables regarding to your API account:
-  - api_key
-  - username
-  - ip_address
- """
+#!/usr/bin/env python
+"""
+Define variables regarding to your API account:
+ - api_key
+ - username
+ - ip_address
+"""
+from namecheap import Api
 
- api = Api(username, api_key, username, ip_address, sandbox=False)
+username = 'MyNamecheapUser'
+api_key = 'SomeAPIKey'
+ip_address = '1.2.3.4'
+api = Api(username, api_key, ip_address, sandbox=False)
 
- domain = "example.org"
+domain = "example.org"
 
- # list domain records
- api.domains_dns_getHosts(domain)
+# list domain records
+api.list_records(domain)
 
- record = {
-  # required
-  "Type": "A",
-  "Name": "test1",
-  "Address": "127.0.0.1",
+# add an 'A' record for subdomain "test" pointing to 127.0.0.1
+api.add_record(domain, 'A', '127.0.0.1', hostname='test', ttl=1800)
 
-  # optional
-  "TTL": "1800",
-  "MXPref": "10"
- }
-
- # add A "test1" record pointing to 127.0.0.1
- api.domains_dns_addHost(domain, record)
-
- # delete record we just created,
- # selecting it by Name, Type and Address values
- api.domains_dns_delHost(domain, record)
+# delete record we just created,
+# selecting it by Name, Type and Address values
+api.delete_record(domain, 'A', '127.0.0.1', hostname='test')
+```
 
 ### Retry mechanism
 
@@ -138,7 +290,7 @@ Sometimes you could face wrong API responses, which are related to server-side e
 Thanks to @gstein, we implemented retry mechanism, one could enable it by adding 2 parameters to Api instance:
 
 ```
-api = Api(username, api_key, username, ip_address, sandbox=False,
+api = Api(username, api_key, ip_address, sandbox=False,
  attempts_count=3,
  attempts_delay=0.1)
 ```

diff --git a/namecheap-api-cli b/namecheap-api-cli
@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 import argparse