Initial Commit

.gitignore

@@ -0,0 +1,92 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+
+# virtualenv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+
+# Rope project settings
+.ropeproject
+
+#pycharm
+.idea/

LICENSE.rst

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2017] [Ujjwal Gupta]
+
+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 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.

MANIFEST.in

@@ -0,0 +1 @@
+include LICENSE.rst README.rst

README.rst

@@ -0,0 +1,269 @@
+**********
+newsapi
+**********
+
+|version| |license|
+
+Python wrapper around ``A JSON API for live news and blog headlines`` (a.k.a. ``News Api``): https://newsapi.org/
+
+**NOTE:** This library and its author are not endorsed by or affiliated with `NewsApi.com <https://newsapi.org/>`_.
+
+
+Installation
+============
+
+Using ``pip``:
+
+
+::
+
+	pip install newsapi
+
+
+Dependencies
+============
+
+- requests
+
+
+API
+===
+
+``newsapi`` offers two classes ``Articles`` and ``Sources`` for the functionality of two endpoints offered by ``News Api`` respectively.
+
+
+Articles
+--------------
+
+=================  ==================  ============================  ===================================================================
+News API Param       newsapi Param       Value                       Description
+=================  ==================  ============================  ===================================================================
+``source``              ``source``         string **(required)**     The identifer for the news source or blog you want headlines from
+``apiKey``              ``API_KEY``        string **(required)**     Your API key.
+``sortBy``              ``sort_by``        string **(optional)**     Specify which type of list you want. The possible options are **top**, **latest** and **popular**.  **Note**: not all options are available for **all** sources. **Default**: **top**.
+=================  ==================  ============================  ===================================================================
+
+Methods
+-------
+
+All methods of ``Articles`` are accessible via:
+
+
+.. code-block:: python
+
+   from newsapi.articles import articles
+
+   a = Articles(API_KEY="Your-api-key")
+
+   # a.<method>
+
+===================================== ==================================================================================  ============================================================================================ =================
+Method                                Parameters                                                                          Description                                                                                   Returns
+===================================== ==================================================================================  ============================================================================================ =================
+``get()``                              source (required), sort_by (optional), attributes_format (optional Default:True)    Generic request to NewsApi (with source as required parameter, sort_by as optional).         ``AttrDict``
+``get_by_top()``                       source (required)                                                                   Requests a list of the source's headlines sorted in the order they appear on its homepage.   ``AttrDict``
+``get_by_latest()``                    source (required).                                                                  Requests a list of the source's headlines sorted in chronological order, newest first.       ``AttrDict``
+``get_by_popular()``                   source (required).                                                                  Requests a list of the source's current most popular or currently trending headlines.        ``AttrDict``
+===================================== ==================================================================================  ============================================================================================ =================
+
+**NOTE:** By default all ``newsapi`` responses are formatted as ``JSON``, ``AttrDict`` is just a wrapper around Dictionary which enables to do content.status as well as content['status'], but can't do it in nested dicts.
+
+Usage
+=====
+
+
+General Import
+--------------
+
+
+.. code-block:: python
+
+	from newsapi.articles import Articles
+
+    a = Articles(API_KEY="Your-api-key")
+
+
+a.get()
+----------
+
+
+.. code-block:: python
+
+	# get all the articles from the new web and sorted by top (default).
+	a.get(source="the-new-web")
+
+
+a.get_by_popular()
+---------------------------------------
+
+
+.. code-block:: python
+
+	# get all the articles from the new web and sorted by popular (front page).
+	a.get_by_popular(source="the-new-web")
+
+
+
+Sources
+--------------
+
+=================  ==================  ============================  ===================================================================
+News API Param       newsapi Param       Value                       Description
+=================  ==================  ============================  ===================================================================
+``category``           ``category``        string **(optional)**     The category you would like to get sources for. **Possible options**: *business*, *entertainment*, *gaming*, *general*, *music*, *science-and-nature*, *sport*, *technology*. **Default**: **empty** *(all sources returned)*
+``language``           ``language``        string **(optional)**     The 2-letter ISO-639-1 code of the language you would like to get sources for. **Possible options**: *en*, *de*, *fr*. **Default**: **empty** *(all sources returned)*.
+``country``            ``country``         string **(optional)**     The 2-letter ISO 3166-1 code of the country you would like to get sources for. **Possible options**: *au*, *de*, *gb*, *in*, *it*, *us*. **Default**: **empty** *(all sources returned)*.
+=================  ==================  ============================  ===================================================================
+
+Methods
+-------
+
+All methods are accessible via:
+
+
+.. code-block:: python
+
+   from newsapi.sources import Sources
+
+   s = Sources(API_KEY="Your-api-key")
+
+   # s.<method>
+
+
+====================================== ========================================================================================================== =============================================================================================================== ========================
+Method                                 Parameters                                                                                                 Description                                                                                                     Returns
+====================================== ========================================================================================================== =============================================================================================================== ========================
+``get()``                              category (optional), language (optional), country (optional), attributes_format (optional Default:True).   Generic request to NewsApi to get sources as needed with optional params. (default : empty returns all sources  ``AttrDict``
+``all()``                              No parameters needed.                                                                                      wrapper around get() to get all sources unfiltered.                                                             ``AttrDict``
+``get_by_category()``                  category (required).                                                                                       The category you would like to get sources for.                                                                 ``AttrDict``
+``get_by_language()``                  language (required).                                                                                       The 2-letter ISO-639-1 code of the language you would like to get sources for.                                  ``AttrDict``
+``get_by_language()``                  country (required).                                                                                        The 2-letter ISO 3166-1 code of the country you would like to get sources for.                                  ``AttrDict``
+``information()``                      No parameters needed.                                                                                      Sets up everything by sending an unfiltered request and then sorting it.                                        ``Self``
+``all_sorted_information()``           No parameters needed.                                                                                      gives back all the sources.                                                                                     ``Array``
+``all_categories``                     detailed (optional, Default: False, gives all the information of sources group by categories).             Gets all the categories available by newsapi and grouped with info if detailed set to true.                     ``dict_keys``/``Dict``
+``all_languages``                      detailed (optional, Default: False, gives all the information of sources group by languages).              Gets all the languages available by newsapi and grouped with info if detailed set to true.                      ``dict_keys``/``Dict``
+``all_countries``                      detailed (optional, Default: False, gives all the information of sources group by countries).              Gets all the countries available by newsapi and grouped with info if detailed set to true.                      ``dict_keys``/``Dict``
+``all_base_information()``             No parameters needed.                                                                                      gives back all the name, id pairs of the available sources offered by newsapi.                                  ``Dict``
+``all_ids()``                          detailed (optional, Default: False, gives name, id pair of all the sources).                               gives back all the ids of the available sources offered by newsapi.                                             ``dict_values``/``Dict``
+``all_names()``                        detailed (optional, Default: False, gives name, url pair of all the sources).                              gives back all the names of the available sources offered by newsapi.                                           ``dict_keys``/``Dict``
+``all_urls()``                         detailed (optional, Default: False, gives name, url pair of all the sources).                              gives back all the urls of the available sources offered by newsapi.                                            ``dict_values``/``Dict``
+``search()``                           name (required, the name of the source you wanna search for).                                              gives back all the matches from the given name of the source to avaiable ones by newsapi with all the info.     ``Array``
+====================================== ========================================================================================================== =============================================================================================================== ========================
+
+**NOTE:** By default all ``newsapi`` responses are formatted as ``JSON``, ``AttrDict`` is just a wrapper around Dictionary which enables to do content.status as well as content['status'], but can't do it in nested dicts.
+
+
+
+Usage
+=====
+
+
+General Import
+--------------
+
+
+.. code-block:: python
+
+	from newsapi.sources import Sources
+
+    s = Sources(API_KEY="Your-api-key")
+
+
+s.get()
+----------
+
+
+.. code-block:: python
+
+	# get sources with category technology and language as en while originated from country uk
+	s.get(category='technology', language='en', country='uk')
+
+
+
+s.all()
+----------
+
+
+.. code-block:: python
+
+	# get all sources offered by newsapi
+	s.all()
+
+
+
+s.get_by_category()
+--------------------
+
+
+.. code-block:: python
+
+	# get all sources offered by newsapi with category as general
+	s.get_by_category("general")
+
+
+
+s.information()
+--------------------
+
+
+.. code-block:: python
+
+	# sets up everything and sorts the raw data.
+	s.information()
+
+	#then you can chain functions, so instead of above command use this.
+	#gets all the categories offered by newsapi.
+	s.information().all_categories()
+
+	#or just call it standalone like so.
+	s.information()
+	s.all_categories()
+
+	#using detailed parameter results in categories group with sources info like
+	s.information().all_categories(detailed=True)
+	#results in:
+	# ['general' : [{'id': "the-new-web", 'name': "The New Web"}, ...], 'sports': [{'id': "bbc-sports", 'name': "The BBC Sports"},...], ...]
+
+
+s.all_base_information()
+---------------------------
+
+
+.. code-block:: python
+
+	# get all sources in the name, url pair dict format offered by newsapi
+	s.information().all_base_information()
+
+
+
+s.all_ids()
+-------------
+
+
+.. code-block:: python
+
+	# get all sources ids offered by newsapi
+	s.information().all_ids()
+
+
+s.search()
+-------------
+
+
+.. code-block:: python
+
+	# search by string
+	s.search('bbc')
+	#results with array containing all the sources which has 'bbc' string present in it with all its info.
+
+Errors and Exceptions
+=====================
+
+Under the hood, ``newsapi`` uses the `requests <http://www.python-requests.org/>`_ library. For a listing of explicit exceptions raised by ``requests``, see `Requests: Errors and Exceptions <http://www.python-requests.org/en/latest/user/quickstart/#errors-and-exceptions>`_.
+
+
+.. |version| image:: http://img.shields.io/pypi/v/omdb.svg?style=flat-square
+    :target: https://pypi.python.org/pypi/newsapi
+
+.. |license| image:: http://img.shields.io/pypi/l/omdb.svg?style=flat-square
+    :target: https://pypi.python.org/pypi/newsapi

setup.cfg

@@ -0,0 +1,5 @@
+[bdist_wheel]
+# This flag says that the code is written to work on both Python 2 and Python
+# 3. If at all possible, it is good practice to do this. If you cannot, you
+# will need to generate wheels for each Python version that you support.
+universal=1