Merge pull request #5 from Stewart86/refine-documentations

Refine documentations

Author: Stewart86

.gitignore

@@ -53,13 +53,6 @@ cover/
 *.mo
 *.pot
 
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow
 __pypackages__/
 
@@ -75,7 +68,7 @@ __pypackages__/
 dmypy.json
 
 # vscode
-vscode/
+.vscode/
 .vscode/settings.json
 .vscode/launch.json
 

CONTRIBUTING.rst

@@ -8,7 +8,6 @@ welcomes contributions in the form of bug reports, feature requests, and pull re
 Here is a list of important resources for contributors:
 
 - `Source Code`_
-- `Documentation`_
 - `Issue Tracker`_
 - `Code of Conduct`_
 
@@ -57,11 +56,6 @@ Install the package with development requirements:
 You can now run an interactive Python session,
 or the command-line interface:
 
-.. code:: console
-
-   $ poetry run python
-   $ poetry run aiocloudflare
-
 .. _Poetry: https://python-poetry.org/
 .. _Nox: https://nox.thea.codes/
 .. _nox-poetry: https://nox-poetry.readthedocs.io/

README.rst

@@ -32,9 +32,9 @@ aioCloudflare
    :target: https://github.com/psf/black
    :alt: Black
 
-Inspired by the offical `python-cloudflare` library developed by `Cloudflare`_. This project is created to be competible to use with `asyncio` for non-blocking IO.
+Inspired by the offical ``python-cloudflare`` library developed by `Cloudflare`_. This project is created to be compatible with ``asyncio`` for non-blocking IO.
 
-For sync code, it is recommanded to use `python-cloudflare` via `pip install python-cloudflare` as it is used by hundreds and offically maintained by cloudflare. This ensure that APIs are always updated according to Cloudflare API release.
+For sync code, it is recommanded to use ``python-cloudflare`` via ``pip install python-cloudflare`` as it is used by hundreds and offically maintained by Cloudflare. This ensure that APIs are always updated according to Cloudflare API release.
 
 *NOTE:* This library is in Pre-Alpha, this means things might break. Do not use it in Production unless you have tested on the API route specific to your use case and that would be at your own risk.
 
@@ -47,6 +47,13 @@ Features
 * Autocompletion on IDE.
 * Fully type hinted.
 
+Feature Roadmap
+---------------
+
+* to support cert token
+* to support sync API client
+* to get to 100% test coverage
+
 
 Requirements
 ------------
@@ -86,6 +93,18 @@ Full configuration can be done using `Config()` class.
         async with Cloudflare(config=config) as cf:
             result = await cf.zones.get()
 
+Configuration can also be stored in a ``.env`` file for a "global configuration without needing to create a ``Config()`` class. Keys available are:
+
+.. code:: console
+
+    CF_API_EMAIL=""
+    CF_API_KEY=""
+    CF_API_CERTKEY=""
+    CF_API_URL=""
+    DEBUG=false
+    CF_PROFILE=""
+    USER_AGENT=""
+
 
 Contributing
 ------------
@@ -112,6 +131,6 @@ please `file an issue`_ along with a detailed description.
 .. _PyPI: https://pypi.org/
 .. _file an issue: https://github.com/stewart86/aiocloudflare/issues
 .. _pip: https://pip.pypa.io/
+.. _Cloudflare: https://github.com/cloudflare/python-cloudflare
 .. github-only
 .. _Contributor Guide: CONTRIBUTING.rst
-.. _Cloudflare: https://cloudflare.com

aiocloudflare/cloudflare.py

@@ -32,6 +32,8 @@ class ClientState(Enum):
 
 
 class Cloudflare:
+    """Cloudflare API Client, a main entry point to all API endpoints."""
+
     def __init__(
         self,
         email: Optional[str] = None,
@@ -46,6 +48,42 @@ def __init__(
         logger: Optional[Logger] = None,
         config: Optional[Config] = None,
     ) -> None:
+        """To initalise with async context manager for async calls.
+        This Class currently only support async operations. To use sync operations,
+        please use Cloudflare offical Python library `python-cloudflare`
+
+        >>> async with Cloudflare() as cf:
+        >>>     result = await cf.zones.get()
+
+        An optional `Config()` class can also be use to configure the Cloudflare
+        instance. When initialised with the config class parameter, all other
+        parameters will be ignored.
+
+        >>> from aiocloudflare import Cloudflare, Config
+        >>>
+        >>>
+        >>> config = Config(email="[email protected]", token="<secret>")
+        >>> async with Cloudflare(config=config) as cf:
+        >>>     result = await cf.zones.get()
+
+        Args:
+            email (Optional[str], optional):
+                Registered email to Cloudflare API. Defaults to None.
+            token (Optional[str], optional):
+                API token from Cloudflare. Defaults to None.
+            certtoken (Optional[str], optional):
+                To use Cert Token **current not implemented**. Defaults to None.
+            raw (Optional[str], optional): Not Implemented. Defaults to None.
+            base_url (Optional[str], optional): If not provided, it will
+                defaults to cloudflare's v4 API. Defaults to None.
+            debug (Optional[bool], optional): To set debug as true, logs will
+                be more verbose. Defaults to False.
+            test (Optional[bool], optional): If True, config will ignore all
+                args in the init method and use a seperate config must be
+                provided. Defaults to None.
+            config (Optional[Config], optional): An optional config class
+                include all settings. Defaults to None.
+        """
         if config:
             self._config = config
         else:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "aiocloudflare"
-version = "0.1.2-alpha"
+version = "0.1.3-alpha"
 description = "A Cloudflare API wrapper for Python with asyncio support"
 authors = ["Stewart Wong <[email protected]>"]
 license = "MIT"
@@ -11,7 +11,6 @@ classifiers = [
     "Development Status :: 2 - Pre-Alpha",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.8",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]