{ "info": { "author": "Christopher H. Casebeer", "author_email": "UNKNOWN", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "License :: OSI Approved :: BSD License" ], "description": "Factual Server API Wrapper\n==========================\n\nThis package wraps the `Factual v3\nAPI `_.\nIts query style is SQLAlchemy-inspired and designed to make it easy to\nbuild \"read\" requests by chaining filter calls together.\n\nThere is also limited support for v2 API, including actions other than\n\"read,\" under the \"v2\" subpackage.\n\nNote that there are minor API inconsistencies between the v2 and v3\nversions, both on the server side and in this wrapper. The v3 version of\nthe wrapper is now the default.\n\nAPI access\n----------\n\nTo get started, you'll need to `register for Factual API OAuth\ncredentials `_.\n\nUsage\n-----\n\nFirst, create a Session using your v3 API OAuth consumer key and\nconsumer secret:\n\n::\n\n import factual\n session = factual.Session(\n consumer_key=\"myOAuthConsumerKey\",\n consumer_secret=\"myOAuthConsumerSecret\"\n )\n\nNow, build a query using the ``read`` action on the ``\"global\"`` table:\n\n::\n\n query = session.read(\"global\")\n\nYou can apply as many filters as you'd like to the query. Filters on a\nquery are cumulative, and can be chained:\n\n::\n\n query.search(\"coffee\")\n query.filter({\"locality\": \"Albany\"}).filter({\"region\":\"NY\"})\n\nWhen you're done, ``run()`` the query and retrieve the results using the\n``records()`` method:\n\n::\n\n from pprint import pprint\n\n data = query.run().records()\n pprint(data)\n\nGeographic queries\n~~~~~~~~~~~~~~~~~~\n\nYou probably want to search for places near a point. Use the\n``within(latitude, longitude, radius_in_meters)`` helper method of\n``read``. ``within()`` chains and applies like any other filter, except\nthat the last call will overwrite earlier geo filters. The underlying\nFactual filter API has changed between v2 and v3, but this will work for\nboth:\n\n::\n\n query = session.read(\"global\").within(40.7353,-73.9912,1000).search(\"coffee\")\n\nPagination\n~~~~~~~~~~\n\nGet more results using ``count()`` and ``page()``:\n\n::\n\n query.count(30).page(2) # 30 results per request, second page of results\n\nNote that Factual's API instead uses ``limit`` and ``offset``, so I\nshould probably change the wrapper to match.\n\nCategories\n~~~~~~~~~~\n\nFactual provides categories as hierarchical strings. That is, any place\nmarked \"Food & Beverage > Bakeries\" is in the \"Bakeries\" subcategory of\n\"Food & Beverage.\"\n\nIt's possible to query for either specific subcategories or parent\ncategories using the ``$bw`` (\"begins with\") filter operator. You can\nthen search across multiple of these ``$bw`` filters by chaining them\ntogether with ``$or``.\n\nBecause this can get pretty lengthy, the ``category_helpers`` module has\na ``make_category_filter`` function. ``make_category_filter`` takes a\nlist of category strings and combines them into a ``$bw``/``or`` filter.\nSince ``$bw`` will always include all subcategories of an supercategory\nlisted, ``make_category_filter`` also dedupes the provided categories to\ngenerate the shortest list possible. This may mean that it will include\nmore subcategories than you indended; but if you want to get in to\n``$and $not $bw`` tangles, you're on your own.\n\nPass ``blank = True`` as a kwarg to ``make_category_filter`` if you also\nwant results without categories set.\n\n::\n\n from factual import category_helpers\n\n my_categories = [ \"Food & Beverage\", \"Food & Beverage > Bakeries\", \"Shopping\" ]\n my_filters = category_helpers.make_category_filter(my_categories, blank=True)\n # {'$or': ({'category': {'$bw': 'Food & Beverage'}}, {'category': {'$bw': 'Shopping'}}, {'category': {'$blank': True}})}\n\n query = s.read(\"global\").filter(my_filters)\n\nNon-OAuth requests\n~~~~~~~~~~~~~~~~~~\n\nIt's possible to skip OAuth for the v3 API, if, for instance, there's\nsome trouble with signing requests. Creating a Session without a\n``consumer_secret`` will authenticate requests via the ``KEY`` query\nstring parameter rather than OAuth:\n\n::\n\n non_oauth_session = factual.Session(consumer_key=\"myOAuthConsumerKey\")\n\nNote that Factual `discourages falling back to the KEY\nparameter `_,\nand intends it for debugging use only, so use OAuth if possible.\n\nExamples\n--------\n\n::\n\n from factual import *\n s = Session(consumer_key=\"deadbeef\", consumer_secret=\"foobar\")\n my_place = s.read(\"global\").search(\"coffee\").run().records()[0]\n\nBuilding requests one piece at a time:\n\n::\n\n query = s.read(\"global\")\n query.filter({\"name\": \"Foobar\"})\n if my_address != None:\n query.filter({\"address\": my_address})\n response = query.run()\n records = response.records()\n\nLimiting categories and using the filter helper functions:\n\n::\n\n from factual.filter_helpers import *\n q = s.read(\"global\").filter(\n or_(\n bw_(\"category\", \"Food\"), \n bw_(\"category\", \"Arts\")\n )\n ).search(\"Foobar\")\n records = q.run().records()\n\nGeo queries:\n\n::\n\n # lat, lon, radius in meters\n coffee_places = s.read(places).search(\"coffee\").within(40.7353,-73.9912,1000).run().records()\n\nFactual v2 \"Server\" API\n-----------------------\n\nTo use the v2 API, instantiate a factual.v2.Session object instead of a\nfactual.Session object:\n\n::\n\n import factual\n v2_session = factual.v2.Session(api_key=\"deadbeef\")\n ...\n\nNote that you'll need to provide a v2 API key using the ``api_key``\nargument. Factual issues v2 API keys via a different process than for v3\nAPI credentials.\n\nIn the v2 API, you can also modify a record in the Playpen:\n\n::\n\n v2_session = factual.v2.Session(api_key=\"deadbeef\")\n p = v2_session.read(USLocalPlaypen).search(\"coffee\").count(1).run().records()[0]\n p['address'] += \"/Foobar\"\n v2_session.input(USLocalPlaypen).values(p).comment(\"Silly update test\").run()\n\nSee also the Python documentation for session.Session and requests.Read\nand `Factual's developer\ndocumentation `_.\n\nTODO\n----\n\n- Write support for v3, when available\n- Multiple search filters (search filters currently replace one\n another)\n\nChangelog\n---------\n\n- v0.1.2 - Add async option to ``Request.run()`` to permit delaying the\n processing of the HTTP response. If the asynchttp module is\n installed, this will cause the initial call to ``run(async=True)`` to\n immediately return a ``get_response`` function, allowing you to defer\n the blocking call until the results are needed.", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/casebeer/factual", "keywords": null, "license": "UNKNOWN", "maintainer": null, "maintainer_email": null, "name": "factual", "package_url": "https://pypi.org/project/factual/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/factual/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/casebeer/factual" }, "release_url": "https://pypi.org/project/factual/0.1.3/", "requires_dist": null, "requires_python": null, "summary": "Wrapper for the Factual HTTP API.", "version": "0.1.3" }, "last_serial": 751042, "releases": { "0.1.3": [ { "comment_text": "", "digests": { "md5": "9417020216ab41134fac547cb5220a68", "sha256": "d9b3456b0c30370deff8692f218b0718b738af81d05a21104f77f423e73307e3" }, "downloads": -1, "filename": "factual-0.1.3.tar.gz", "has_sig": true, "md5_digest": "9417020216ab41134fac547cb5220a68", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14264, "upload_time": "2012-07-07T02:08:02", "url": "https://files.pythonhosted.org/packages/02/fe/293b3439b24d31d508ef3c96175b1fbc434d86b22415079b09c56b27faa3/factual-0.1.3.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "9417020216ab41134fac547cb5220a68", "sha256": "d9b3456b0c30370deff8692f218b0718b738af81d05a21104f77f423e73307e3" }, "downloads": -1, "filename": "factual-0.1.3.tar.gz", "has_sig": true, "md5_digest": "9417020216ab41134fac547cb5220a68", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14264, "upload_time": "2012-07-07T02:08:02", "url": "https://files.pythonhosted.org/packages/02/fe/293b3439b24d31d508ef3c96175b1fbc434d86b22415079b09c56b27faa3/factual-0.1.3.tar.gz" } ] }