diff --git a/README.rst b/README.rst index 70e04b0..ae15a7e 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ Python Twitter Search API This library serves as a python interface to the `Twitter premium and enterprise search APIs `_. It provides a command-line utility and a library usable from within python. It comes with tools for assisting in dynamic generation of search rules and for parsing tweets. -Pretty docs can be seen `here `_. +Pretty docs can be seen `here `_. Features @@ -22,18 +22,18 @@ Features Installation ============ -We will soon handle releases via PyPy, but you can also install the current master version via +We will host the package on PyPi so it's pip-friendly. .. code:: bash - pip install git+https://github.com/twitterdev/twitter_search_api.git + pip install searchtweets Or the development version locally via .. code:: bash - git clone https://github.com/twitterdev/twitter_search_api.git - cd twitter_search_api + git clone https://github.com/twitterdev/search-tweets-python + cd search-tweets-python pip install -e . @@ -41,7 +41,7 @@ Or the development version locally via Using the Comand Line Application ================================= -We provide a utility, ``twitter_search.py``, in the ``tools`` directory that provides rapid access to tweets. +We provide a utility, ``search_tweets.py``, in the ``tools`` directory that provides rapid access to tweets. Premium customers should use ``--bearer-token``; enterprise customers should use ``--user-name`` and ``--password``. The ``--endpoint`` flag will specify the full URL of your connection, e.g.: @@ -61,7 +61,7 @@ Note that the ``--results-per-call`` flag specifies an argument to the API call .. code:: bash - python twitter_search.py \ + python search_tweets.py \ --bearer-token \ --endpoint \ --max-results 1000 \ @@ -74,7 +74,7 @@ Note that the ``--results-per-call`` flag specifies an argument to the API call .. code:: bash - python twitter_search.py \ + python search_tweets.py \ --user-name \ --password \ --endpoint \ @@ -89,7 +89,7 @@ Note that the ``--results-per-call`` flag specifies an argument to the API call .. code:: bash - python twitter_search.py \ + python search_tweets.py \ --user-name \ --password \ --endpoint \ @@ -134,7 +134,7 @@ When using a config file in conjunction with the command-line utility, you need Example:: - python twitter_search_api.py \ + python search_tweets.py \ --config-file myapiconfig.config \ --no-print-stream @@ -160,7 +160,7 @@ Your credentials should be put into a YAML file that looks like this: .. code:: yaml - twitter_search_api: + search_tweets_api: endpoint: account: username: @@ -181,7 +181,7 @@ throughout your program's session. .. code:: python - from twittersearch import ResultStream, gen_rule_payload, load_credentials + from searchtweets import ResultStream, gen_rule_payload, load_credentials Enterprise setup ---------------- @@ -257,7 +257,7 @@ Let's see how it goes: .. code:: python - from twittersearch import collect_results + from searchtweets import collect_results .. code:: python diff --git a/docs/Makefile b/docs/Makefile index 24f7952..4895a31 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,7 +4,7 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -SPHINXPROJ = twittersearchapi +SPHINXPROJ = searchtweetsapi SOURCEDIR = source BUILDDIR = build @@ -17,4 +17,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0463868..967c845 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -55,7 +55,7 @@ master_doc = 'index' # General information about the project. -project = 'twitter search api' +project = 'Twitter Search APIs Python Wrapper' copyright = '2017, twitterdev' author = 'twitterdev' @@ -64,9 +64,9 @@ # built documents. # # The short X.Y version. -version = '0.1' +version = '1.0' # The full version, including alpha/beta/rc tags. -release = '0.1' +release = '1.0b' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -112,7 +112,7 @@ # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. -htmlhelp_basename = 'twittersearchdoc' +htmlhelp_basename = 'searchtweetsdoc' # -- Options for LaTeX output --------------------------------------------- @@ -139,7 +139,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'twittersearch.tex', 'twitter search api Documentation', + (master_doc, 'searchtweets.tex', 'twitter search api Documentation', 'twitterdev', 'manual'), ] @@ -149,7 +149,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'twittersearch', 'twitter search api Documentation', + (master_doc, 'searchtweets', 'twitter search api Documentation', [author], 1) ] @@ -160,8 +160,8 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'twittersearch', 'twitter search api Documentation', - author, 'twittersearch', 'One line description of project.', + (master_doc, 'searchtweets', 'twitter search api Documentation', + author, 'searchtweets', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/source/index.rst b/docs/source/index.rst index 018df3f..a4774e9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,7 +11,7 @@ :caption: Contents: self - twittersearch + searchtweets diff --git a/docs/source/modules.rst b/docs/source/modules.rst index c8f9bb9..0b36c59 100644 --- a/docs/source/modules.rst +++ b/docs/source/modules.rst @@ -1,7 +1,7 @@ -twittersearch +searchtweets ============= .. toctree:: :maxdepth: 4 - twittersearch + searchtweets diff --git a/docs/source/twittersearch.rst b/docs/source/searchtweets.rst similarity index 60% rename from docs/source/twittersearch.rst rename to docs/source/searchtweets.rst index 794df15..34bda72 100644 --- a/docs/source/twittersearch.rst +++ b/docs/source/searchtweets.rst @@ -1,29 +1,29 @@ -twittersearch package +searchtweets package ===================== Submodules ---------- -twittersearch\.api\_utils module +searchtweets\.api\_utils module -------------------------------- -.. automodule:: twittersearch.api_utils +.. automodule:: searchtweets.api_utils :members: :undoc-members: :show-inheritance: -twittersearch\.result\_stream module +searchtweets\.result\_stream module ------------------------------------ -.. automodule:: twittersearch.result_stream +.. automodule:: searchtweets.result_stream :members: :undoc-members: :show-inheritance: -twittersearch\.utils module +searchtweets\.utils module --------------------------- -.. automodule:: twittersearch.utils +.. automodule:: searchtweets.utils :members: :undoc-members: :show-inheritance: @@ -32,7 +32,7 @@ twittersearch\.utils module Module contents --------------- -.. automodule:: twittersearch +.. automodule:: searchtweets :members: :undoc-members: :show-inheritance: diff --git a/examples/api_example.ipynb b/examples/api_example.ipynb index 1e14149..2f28d99 100644 --- a/examples/api_example.ipynb +++ b/examples/api_example.ipynb @@ -41,7 +41,7 @@ }, "outputs": [], "source": [ - "from twittersearch import ResultStream, gen_rule_payload, load_credentials" + "from searchtweets import ResultStream, gen_rule_payload, load_credentials" ] }, { @@ -149,7 +149,7 @@ }, "outputs": [], "source": [ - "from twittersearch import collect_results" + "from searchtweets import collect_results" ] }, { diff --git a/examples/readme.rst b/examples/readme.rst index 53cd816..df8b17f 100644 --- a/examples/readme.rst +++ b/examples/readme.rst @@ -41,7 +41,7 @@ throughout your program's session. .. code:: python - from twittersearch import ResultStream, gen_rule_payload, load_credentials + from searchtweets import ResultStream, gen_rule_payload, load_credentials Enterprise setup ---------------- @@ -117,7 +117,7 @@ Let's see how it goes: .. code:: python - from twittersearch import collect_results + from searchtweets import collect_results .. code:: python diff --git a/twittersearch/__init__.py b/searchtweets/__init__.py similarity index 100% rename from twittersearch/__init__.py rename to searchtweets/__init__.py diff --git a/twittersearch/api_utils.py b/searchtweets/api_utils.py similarity index 94% rename from twittersearch/api_utils.py rename to searchtweets/api_utils.py index 3ae1dbf..f8f2964 100644 --- a/twittersearch/api_utils.py +++ b/searchtweets/api_utils.py @@ -15,7 +15,7 @@ import json __all__ = ["gen_rule_payload", "gen_params_from_config", "load_credentials", - "infer_endpoint", + "infer_endpoint", "convert_utc_time", "validate_count_api", "GNIP_RESP_CODES", "change_to_count_endpoint"] logger = logging.getLogger(__name__) @@ -65,7 +65,7 @@ def convert_utc_time(datetime_str): string of GNIP API formatted date. Example: - >>> from twittersearch.utils import convert_utc_time + >>> from searchtweets.utils import convert_utc_time >>> convert_utc_time("201708020000") '201708020000' >>> convert_utc_time("2017-08-02") @@ -136,7 +136,7 @@ def gen_rule_payload(pt_rule, results_per_call=500, Example: - >>> from twittersearch.utils import gen_rule_payload + >>> from searchtweets.utils import gen_rule_payload >>> gen_rule_payload("kanye west has:geo", ... from_date="2017-08-21", ... to_date="2017-08-22") @@ -221,12 +221,12 @@ def validate_count_api(rule_payload, endpoint): def load_credentials(filename=None, account_type=None): """ - handlles credeintial managmenet via a YAML file. YAML files should look + Handles credeintial managmenet via a YAML file. YAML files should look like this: .. code:: yaml - twitter_search_api: + search_tweets_api: endpoint: account: username: @@ -240,13 +240,14 @@ def load_credentials(filename=None, account_type=None): default '~/.twitter_keys.yaml' account_type (str): pass your account type, "premium" or "enterprise" - Returns: dict of your access credentials. + Returns: + dict of your access credentials. Example: - >>> from twittersearch.api_utils import load_credentials - >>> search_args = load_credentials(account_type="premium") - >>> search_args.keys() - dict_keys(['bearer_token', 'endpoint']) + >>> from searchtweets.api_utils import load_credentials + >>> search_args = load_credentials(account_type="premium") + >>> search_args.keys() + dict_keys(['bearer_token', 'endpoint']) """ if account_type is None or account_type not in {"premium", "enterprise"}: @@ -254,7 +255,7 @@ def load_credentials(filename=None, account_type=None): raise KeyError filename = "~/.twitter_keys.yaml" if filename is None else filename with open(os.path.expanduser(filename)) as f: - search_creds = yaml.load(f)["twitter_search_api"] + search_creds = yaml.load(f)["search_tweets_api"] try: diff --git a/twittersearch/result_stream.py b/searchtweets/result_stream.py similarity index 97% rename from twittersearch/result_stream.py rename to searchtweets/result_stream.py index 8be4d5c..4a62b8d 100644 --- a/twittersearch/result_stream.py +++ b/searchtweets/result_stream.py @@ -16,8 +16,11 @@ import json from tweet_parser.tweet import Tweet -from .utils import * -from .api_utils import * +from .utils import merge_dicts + +from .api_utils import (infer_endpoint, GNIP_RESP_CODES, + change_to_count_endpoint) + logger = logging.getLogger(__name__) @@ -30,7 +33,7 @@ def make_session(username=None, password=None, bearer_token=None): Args: username (str): username for the session password (str): password for the user - bearer_token (str): token for the session for freemium. + bearer_token (str): token for a premium API user. """ if password is None and bearer_token is None: @@ -226,7 +229,7 @@ def init_session(self): def check_counts(self): """ - Disables tweet parsing if the count api is used. + Disables tweet parsing if the count API is used. """ if "counts" in re.split("[/.]", self.endpoint): logger.info("disabling tweet parsing due to counts api usage") @@ -278,7 +281,7 @@ def collect_results(rule, max_results=500, result_stream_args=None): list of results Example: - >>> from twittersearch import collect_results + >>> from searchtweets import collect_results >>> tweets = collect_results(rule, max_results=500, result_stream_args=search_args) diff --git a/twittersearch/utils.py b/searchtweets/utils.py similarity index 93% rename from twittersearch/utils.py rename to searchtweets/utils.py index 22701d7..0794df2 100644 --- a/twittersearch/utils.py +++ b/searchtweets/utils.py @@ -22,7 +22,12 @@ def take(n, iterable): - "Return first n items of the iterable as a list" + """Return first n items of the iterable as a list + + Args: + n (int): number of items to return + iterable (iterable): the object to select + """ return it.islice(iterable, n) @@ -31,7 +36,7 @@ def partition(iterable, chunk_size, pad_none=False): certain chunk size, padding with Nones if availble. Example: - >>> from twittersearch.utils import partition + >>> from searchtweets.utils import partition >>> iter_ = range(10) >>> list(partition(iter_, 3)) [(0, 1, 2), (3, 4, 5), (6, 7, 8)] @@ -58,7 +63,7 @@ def merge_dicts(*dicts): the sequence will override duplicate keys from previous dictionaries. Example: - >>> from twittersearch.utils import merge_dicts + >>> from searchtweets.utils import merge_dicts >>> d1 = {"rule": "something has:geo"} >>> d2 = {"maxResults": 1000} >>> merge_dicts(*[d1, d2]) diff --git a/setup.py b/setup.py index 42b8a5d..241bb09 100644 --- a/setup.py +++ b/setup.py @@ -1,14 +1,14 @@ from setuptools import setup, find_packages -setup(name='twittersearch', +setup(name='searchtweets', description="Wrapper for Twitter's Premium and Enterprise search APIs", url='https://github.com/twitterdev/twitter_search_api', author='Fiona Pigott, Jeff Kolb, Josh Montague, Aaron Gonzales', long_description=open('README.rst', 'r').read(), author_email='agonzales@twitter.com', license='MIT', - version='0.1.3', + version='1.0', install_requires=["requests", "tweet_parser", "pyyaml"], packages=find_packages(), - scripts=["tools/twitter_search.py"], + scripts=["tools/search_tweets.py"], ) diff --git a/tools/twitter_search.py b/tools/search_tweets.py similarity index 98% rename from tools/twitter_search.py rename to tools/search_tweets.py index 3694123..12be3dc 100644 --- a/tools/twitter_search.py +++ b/tools/search_tweets.py @@ -3,9 +3,9 @@ import json import sys import logging -from twittersearch.result_stream import ResultStream -from twittersearch.api_utils import * -from twittersearch.utils import * +from searchtweets.result_stream import ResultStream +from searchtweets.api_utils import * +from searchtweets.utils import * logger = logging.getLogger() # we want to leave this here and have it command-line configurable via the