Metadata-Version: 2.1
Name: domains-api
Version: 0.2.12
Summary: Auto-updates dynamic DNS rules on Google Domains (domains.google.com)
Home-page: https://github.com/nihilok/domains-api
Author: Michael Jarvis
Author-email: mjfullstack@gmail.com
License: UNKNOWN
Description: # Google Domains API Client
        To facilitate running a home web server behind a router without a static IP, this package checks to see if your external IP has changed and automatically updates your Dynamic DNS rules on Google Domains, via the API; also notifies user by email if required.
        
        ### Installation (Python 3.6+):
        `pip install domains-api`
        
        ### Usage:
        Can be run from the command line like so:
        
        `domains-api [opt]`
        
        or imported into your projects in the normal way*:
        ```
        from domains_api.ip_changer import IPChanger
        ipchanger = IPChanger()
        ```
        
        Windows/Mac or Linux, it will ask for your credentials on first run and then shouldn't need any input after that. I added command line options/arguments (see `domains-api --help`) for loading/deleting a profile and changing credentials/settings more easily.
        
        You will need your Dynamic DNS autogenerated username and password as described in [this documentation.](https://support.google.com/domains/answer/6147083?hl=en-CA) For more info on how to set up Dynamic DNS and the process I went through writing this script check [this blog post.](https://mjfullstack.medium.com/running-a-home-web-server-without-a-static-ip-using-google-domains-python-saves-the-day-246570b26d88)
        
        If you choose to receive email notifications, you will be asked to input your gmail email address and password which will then be encoded before being saved as part of a User instance. (The notification is sent from the user's own email address via the gmail smtp server, you might need to allow less secure apps on your Google account to use.)
        
        On **Windows** you can use Task Scheduler; on **Linux/Mac**, add a line to your crontab and you can choose the frequency of the checks. An example hourly cron job would look like this:
        
        `0 * * * * domains-api >> ~/cron.log 2>&1`
        
        _assumes package is installed in global scope; otherwise, use command `path/to/env/bin/python3 -m domains_api`_
        
        If reducing downtime is essential, you could increase the frequency of checks to every 1 minute, or even less, like this:
        
        `*/1 * * * * ...etc`
        
        On Google Domains the default TTL for Dynamic DNS is 1 minute, so checks should not need to be more frequent than this, but unless you expect your external IP to change very frequently, such regular cron jobs might be a slight waste of resources; even so, the script is very light weight and usually only takes just over a second to run normally on a Raspberry Pi 3 Ubuntu server.
        
        Check `~/cron.log` if the script does not run as expected, or to see when the IP was last checked.
        
        The logs are written to both `../site_packages/domains_api/domains.log` (posix) or `%LOCALAPPDATA%/domains-api/domains.log` (win), and stdout, so that they also appear in the terminal & crontab log.
        
        After initial setup, the script takes care of everything: if your IP has changed since you last ran it, it will update your Dynamic DNS rule on domains.google.com.
        
        If you forget your IP or need to check it for any reason, running:
        
        `domains-api -i` 
        
        ...will log your current external IP to the terminal without doing anything else.
        
        Other options include:
         
            domains-api                         | set up /or check ip, change if necessary
            domains-api -h --help               | show this help manual
            domains-api -i --ip                 | show current external IP address
            domains-api -f --force              | force domains API call, necessary or not
            domains-api -e --email              | email set up wizard
            domains-api -n --notifications      | toggle email notification settings
            domains-api -d --delete_user        | delete current email/domains profile
            domains-api -l --load_user <path>   | load email/domains profile from file
        
            *User file is saved as "../site-packages/domains_api/domains.user". See same location for log.
        
        In order to use without a domain, run:
        
        `python -m domains_api.ip_checker [opt]`
        
        ### Example in Django application:
        
        In your Django environment:
        
        `pip install domains-api apscheduler`
        
        You must first run the script to set up credentials.
        
        Then, in your project you can create a new module called ip_changer in your project's root directory, with an empty `__init__.py` file and an `ip_changer.py` file.
        
        `ip_changer.py` should look something like this:
        
        ```
        from apscheduler.schedulers.background import BackgroundScheduler
        from domains_api import IPChanger
        
        
        def start():
            scheduler = BackgroundScheduler()
            scheduler.add_job(IPChanger, 'interval', minutes=10)
            scheduler.start()
        ```
        
        Then you will need to add the following to your main app's `apps.py` file:
        
        ```
        class MainConfig(AppConfig):
            name = 'main'
        
            def ready(self):
                from ip_changer import ip_changer
                ip_changer.start()
        ```
        Check `/var/log/apache2/error.log` or `/var/log/nginx/error.log` or your webserver log location (might be logged as wsgi errors) and `..site-packages/domains_api/domains.log` to see everything is working as expected.
        
        Change Log
        ==========
        
        0.2.12 (22/01/2022)
        -------------------
        - better fix for version file not found
        - add version option to args
        - add -D --domain opt to view domain
        
        0.2.10.1 (16/01/2022)
        -------------------
        - hotfix for version file not found
        
        0.2.10 (16/01/2022)
        -------------------
        - getopt --> argparser
        - version constant for setup.py
        
        0.2.9 (16/01/2022)
        ----------------
        - re-add -l --load-user opt
        - skip user creation for --help --ip & --load_user opts
        - stop double check bug
        - add script to path
        - delete user logging bugfix
        
        0.2.6 (29/12/2021)
        ----------------
        - format code
        - refactor
        
        0.2.5.4 (27/08/2021)
        ----------------
        - fixed bug causing -f opt not to fire
        
        0.2.5 (27/06/2021)
        ----------------
        - added '-f' or '--force' option to force api call even if recorded IP hasn't changed.
        
        0.2.4 (25/06/2021)
        ----------------
        - reinstated check if ip changed before API call since refactoring.
        - fixed logging bug re failed emails
        
        0.2.2.1 (12/06/2021)
        ----------------
        - fixed inheritance bug (domains api not being called)
        - relative imports
        
        0.2.1 (15/05/2021)
        ----------------
        - more modular: added IPChecker parent class and BaseUser parent class
        - can be used independent of a domain name to send email notifications.
        - updated README
        
        0.1.6 (02/03/2021)
        ------------------
        - Fixed twitchy email notification bug
        
        0.1.5.2 (09/01/2021)
        --------------------
        - Fixed email outbox (too many emails being sent)
        - Updated README
        - Consistent exit codes
        - Clear logs after 100 lines (keep the last 10 lines)
        - Try/except for permissions (instead of if/else)
        - Other bugfixes/refactoring
        
        0.1.4.8 (08/01/2021)
        --------------------
        - Fixed relative import
        - Changed directory to `/var/www/domains-api/`
        - Updated readme
        - Fixed duplicate loggers
        
        0.1.4.4 (07/01/2021)
        --------------------
        - Refactored all file/log handling methods into file_handlers.FileHandlers
        - Fixed permissions issues (better than before) - run package with sudo the first time to initialize files.
        - Changed posix directory for logs and user files to `domains_api/.domains/`
        - `save_user`/`load_user` and `delete_user` methods are now part of the FileHandlers class.
        
        0.1.4.2 (06/01/2021)
        --------------------
        - Added email outbox for offline messages
        
        0.1.4.1 (05/01/2021)
        --------------------
        - Fixed PermissionError when working with Apache2 & Django (must run script first as www-data e.g: "sudo -u www-data /venv/bin/python -m domains_api" - this will allow the apache server to be the owner of the log/user files when they are set up with least hassle. Missing this set the server will fail with an EOF error, as input is needed to initialize the first User instance. - bear in mind that running the script as a different user in the same environment will fail unless you change permissions on the log/user file located in the package directory)
        - Fixed absolute paths in `User.load_user()` and `User().save_user()` functions.
        - Updated README with Django/Apache2 example.
        
        0.1.3.6 (04/01/2021)
        --------------------
        - Updated GitHub url and long description / readme.
        - Added option to show ip (only) from command line (domains_api -i --ip).
        - Added test function to master branch: simulate change in ip (commented in __main__.py)
        - Minor bugfixes
        
        0.1 - 0.1.2 (03/01/2021)
        ------------------------
        - First Release
        - Code review from:
        https://codereview.stackexchange.com/questions/254272/dynamic-dns-ip-checker-changer-for-google-domains-in-python
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
