Change init() to access_token() and add proxies/verify support.

The name init() didn't make much sense for what it did. It only sets up
your access token if you have a special requirement. setup_logger()
would still need to be run as an "initialization" step if you want to do
logging. So init() has been renamed to access_token() for people who
need to use it.

Folks complained that they need to make connections through proxies or
have special conditions where they need to set verify=False under
certain network conditions. This has been exposed in two ways:

    1) connection(): you can run this and pass a proxies and/or verify
    argument which will be used in all requests.
    2) you can pass a proxies and/or verify argument to class methods
    like .objects(), .details(), etc. which will be used.

    NOTE: passing an argument to class methods will override the global
    settings set by using connection(). This is intentional as it allows
    you to set a general configuration but modify it per-call if
    necessary.

Bumped the version to 0.3.0 due to the API change with init() being
renamed to access_token().

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 -   repo: git://github.com/pre-commit/pre-commit-hooks
-    sha: cf550fcab3f12015f8676b8278b30e1a5bc10e70
+    sha: 29bf11d13689a0a9a895c41eb3591c7e942d377d
     hooks:
     -   id: autopep8-wrapper
         args:
@@ -18,4 +18,4 @@
     -   id: flake8
         args:
         - --exclude=pytx/docs/*,pytx/build/*
-        - --ignore=W291
+        - --ignore=W291

pytx/README.rst

@@ -37,11 +37,11 @@ Quick Example
 
 .. code-block :: python
 
-   from pytx import init
+   from pytx import access_token
    from pytx import ThreatDescriptor
    from pytx.vocabulary import ThreatDescriptor as td
 
-   init('<app-id>', '<app-secret>')
+   access_token('<app-id>', '<app-secret>')
    results = ThreatDescriptor.objects(text='www.facebook.com')
    for result in results:
        print result.get(td.THREAT_TYPES)

pytx/docs/conf.py

@@ -56,9 +56,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.2.0'
+version = '0.3.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.2.0'
+release = '0.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

pytx/docs/index.rst

@@ -15,6 +15,7 @@ Contents:
    quickstart
    pytx.access_token
    pytx.common
+   pytx.connection
    pytx.errors
    pytx.logger
    pytx.malware

pytx/docs/pytx.connection.rst

@@ -0,0 +1,10 @@
+pytx.connection package
+=======================
+
+Module contents
+---------------
+
+.. automodule:: pytx.connection
+    :members:
+    :undoc-members:
+    :show-inheritance:

pytx/docs/quickstart.rst

@@ -12,29 +12,29 @@ The app-id is public knowledge but your app-secret is sensitive. These values
 are provided to you once you've obtained access to ThreatExchange.
 
 pytx will try to find an access token to use or an access token can be passed to
-pytx.access_token.init(). pytx needs an access token before it will function and
-can properly make requests properly. Here are some examples of how to provide
-your access token:
+pytx.access_token.access_token(). pytx needs an access token before it will
+function and can properly make requests properly. Here are some examples of
+how to provide your access token:
 
 .. code-block :: python
 
-  from pytx import init
+  from pytx import access_token
 
   # Use environment variables to build the access token.
   # 1. Use the value of the 'TX_ACCESS_TOKEN' environment variable.
   # 2. Use the concatenation of the 'TX_APP_ID' and 'TX_APP_SECRET' environment variables.
-  # There is no need to call init() if the environment variables are set.
+  # There is no need to call access_token() if the environment variables are set.
 
   # 3. Use a .pytx file which contains your app-id and app-secret.
   # File should be: 'app-id|app-secret' on one line
   # pytx will use either '$PWD/.pytx' or ~/.pytx' if they are found.
-  # There is no need to call init() if the environment variables are set.
+  # There is no need to call access_token() if the environment variables are set.
 
   # 4. Use the concatenation of the app_id and app_secret parameters
-  init(app_id='<app-id>', app_secret='<app-secret>')
+  access_token(app_id='<app-id>', app_secret='<app-secret>')
 
   # 5. Use the first line of the file 'token_file'
-  init(token_file='/path/to/token/file')
+  access_token(token_file='/path/to/token/file')
 
 
 If you need to get the value of the access token pytx is using programmatically,
@@ -60,6 +60,16 @@ information to that file. If the file cannot be written to expect some issues.
 If you do not provide an argument to setup_logger, no logging will occur.
 
 
+If you need to setup a proxy or adjust the verify argument for requests, you can
+use the connection() function to change them. More info can be found here:
+http://docs.python-requests.org/en/latest/api/#requests.request
+
+.. code-block :: python
+
+   from pytx import connection()
+   connection(proxies=<your stuff here>, verify=<your stuff here>)
+
+
 pytx uses classes as the primary method for developer interaction with the
 ThreatExchange API. There are several main classes:
 

pytx/pytx/__init__.py

@@ -1,4 +1,5 @@
-from access_token import init
+from access_token import access_token
+from connection import connection
 from logger import setup_logger
 from request import Broker
 from malware import Malware
@@ -8,7 +9,8 @@
 from threat_indicator import ThreatIndicator
 
 __all__ = [
-    'init',
+    'access_token',
+    'connection',
     'setup_logger',
     'Broker',
     'Malware',

pytx/pytx/access_token.py

@@ -26,18 +26,18 @@ def _read_token_file(token_file):
 
 def get_access_token():
     """
-    Returns the existing access token if init() has been called.
-    Will attempt to init() in the case that there is no access token.
+    Returns the existing access token if access_token() has been called.
+    Will attempt to access_token() in the case that there is no access token.
 
     :raises: :class:`errors.pytxIniterror` if there is no access token.
     """
     global __ACCESS_TOKEN
 
     if not __ACCESS_TOKEN:
-        init()
+        access_token()
 
     if not __ACCESS_TOKEN:
-        raise pytxInitError('Must init() before instantiating')
+        raise pytxInitError('Must access_token() before instantiating')
 
     return __ACCESS_TOKEN
 
@@ -51,12 +51,12 @@ def _find_token_file():
     return None
 
 
-def init(app_id=None, app_secret=None, token_file=None):
+def access_token(app_id=None, app_secret=None, token_file=None):
     """
     Use the app_id and app_secret to store the access_token globally for all
     instantiated objects to leverage.
 
-    There are many ways to specify the app_id and app_secret. In order, init will try:
+    There are many ways to specify the app_id and app_secret. In order, we will try:
      1. Use the value of the 'TX_ACCESS_TOKEN' environment variable.
      2. Use the concatenation of the 'TX_APP_ID' and 'TX_APP_SECRET' environment variables.
      3. Use the first line of the file '$PWD/.pytx' or ~/.pytx'