{
"info": {
"author": "Bruno Rocha",
"author_email": "rochacbruno@gmail.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 2 - Pre-Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: BSD License",
"Natural Language :: English",
"Programming Language :: Python :: 2",
"Programming Language :: Python :: 2.6",
"Programming Language :: Python :: 2.7",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.3"
],
"description": "Create scraper using Scrapy Selectors\n============================================\n\n[](https://travis-ci.org/rochacbruno/splinter_model)\n\n[](https://pypi.python.org/pypi/splinter_model/)\n[](https://pypi.python.org/pypi/splinter_model/)\n\n## What is Splinter?\n\nSplinter is an open source tool for testing web applications using Python. It lets you automate browser actions, such as visiting URLs and interacting with their items.\n\nhttp://splinter.cobrateam.info/\n\n\n## What is splinter_model ?\n\nIt is a clone of [scrapy_model](http://github.com/rochacbruno/scrapy_model) but intead of Scrapy it uses Splinter as engine, so it allows scraping of JavaScript websites.\n\n\n## TODO:\n\nEverything is in to-do, so just dont use it until it is released to PyPI.\n\n### Requirements\n\nThis module should keep implement the same api as scrapy_model, at least the support for CSSField, XPathField, processors, validators, multiple queries and parse_methods.\n\nAlso it should implement a layer to interact with JavaScript.\n\n### Current status: pre-alpha-dev\n\nIt is just a helper to create scrapers using the Scrapy Selectors allowing you to select elements by CSS or by XPATH and structuring your scraper via Models (just like an ORM model) and plugable to an ORM model via ``populate`` method.\n\nImport the BaseFetcherModel, CSSField or XPathField (you can use both)\n\n```python\nfrom splinter_model import BaseFetcherModel, CSSField\n```\n\nGo to a webpage you want to scrap and use chrome dev tools or firebug to figure out the css paths then considering you want to get the following fragment from some page.\n\n```html\n Bruno Rocha website\n```\n\n```python\nclass MyFetcher(BaseFetcherModel):\n name = CSSField('span#person')\n website = CSSField('span#person a')\n # XPathField('//xpath_selector_here')\n```\n\nFields can receive ``auto_extract=True`` parameter which auto extracts values from selector before calling the parse or processors. Also you can pass the ``takes_first=True`` which will for auto_extract and also tries to get the first element of the result, because scrapy selectors returns a list of matched elements.\n\n\n### Multiple queries in a single field\n\nYou can use multiple queries for a single field\n\n```python\nname = XPathField(\n ['//*[@id=\"8\"]/div[2]/div/div[2]/div[2]/ul',\n '//*[@id=\"8\"]/div[2]/div/div[3]/div[2]/ul']\n)\n```\n\nIn that case, the parsing will try to fetch by the first query and returns if finds a match, else it will try the subsequent queries until it finds something, or it will return an empty selector.\n\n#### Finding the best match by a query validator\n\nIf you want to run multiple queries and also validates the best match you can pass a validator function which will take the scrapy selector an should return a boolean.\n\nExample, imagine you get the \"name\" field defined above and you want to validates each query to ensure it has a 'li' with a text \"Schblaums\" in there.\n\n```python\n\ndef has_schblaums(selector):\n for li in selector.css('li'): # takes each inside the ul selector\n li_text = li.css('::text').extract() # Extract only the text\n if \"Schblaums\" in li_text: # check if \"Schblaums\" is there\n return True # this selector is valid!\n return False # invalid query, take the next or default value\n\nclass Fetcher(....):\n name = XPathField(\n ['//*[@id=\"8\"]/div[2]/div/div[2]/div[2]/ul',\n '//*[@id=\"8\"]/div[2]/div/div[3]/div[2]/ul'],\n query_validator=has_schblaums,\n default=\"undefined_name\" # optional\n )\n```\n\nIn the above example if both queries are invalid, the \"name\" field will be filled with an empty_selector, or the value defined in \"default\" parameter.\n\n> **NOTE:** if the field has a \"default\" and fails in all the matcher, the default value will be passed to \"processor\" and also to \"parse_\" methods.\n\nEvery method named ``parse_`` will run after all the fields are fetched for each field.\n\n```python\n def parse_name(self, selector):\n # here selector is the scrapy selector for 'span#person'\n name = selector.css('::text').extract()\n return name\n\n def parse_website(self, selector):\n # here selector is the scrapy selector for 'span#person a'\n website_url = selector.css('::attr(href)').extract()\n return website_url\n\n```\n\n\nafter defined need to run the scraper\n\n\n```python\n\nfetcher = Myfetcher(url='http://.....') # optionally you can use cached_fetch=True to cache requests on redis\nfetcher.parse()\n```\n\nNow you can iterate ``_data``, ``_raw_data`` and atributes in fetcher\n\n```python\n>>> fetcher.name\n\n>>> fetcher.name.value\nBruno Rocha\n>>> fetcher._data\n{\"name\": \"Bruno Rocha\", \"website\": \"http://brunorocha.org\"}\n```\n\nYou can populate some object\n\n```python\n>>> obj = MyObject()\n>>> fetcher.populate(obj) # fields optional\n\n>>> obj.name\nBruno Rocha\n```\n\nIf you do not want to define each field explicitly in the class, you can use a json file to automate the process\n\n```python\nclass MyFetcher(BaseFetcherModel):\n \"\"\" will load from json \"\"\"\n\nfetcher = MyFetcher(url='http://.....')\nfetcher.load_mappings_from_file('path/to/file.json')\nfetcher.parse()\n```\n\nIn that case file.json should be\n\n```json\n{\n \"name\": {\"css\", \"span#person\"},\n \"website\": {\"css\": \"span#person a\"}\n}\n```\n\nYou can use ``{\"xpath\": \"...\"}`` in case you prefer select by xpath\n\n\n### parse and processor\n\nThere are 2 ways of transforming or normalizing the data for each field\n\n#### Processors\n\nA processor is a function, or a list of functions which will be called in the given sequence against the field value, it receives the raw_selector or the value depending on auto_extract and takes_first arguments.\n\nIt can be used for Normalization, Clean, Transformation etc..\n\nExample:\n\n```python\n\ndef normalize_state(state_name):\n # query my database and return the first instance of state object\n return MyDatabase.State.Search(name=state_name).first()\n\ndef text_cleanup(state_name):\n return state_name.strip().replace('-', '').lower()\n\nclass MyFetcher(BaseFetcherModel):\n state = CSSField(\n \"#state::text\",\n takes_first=True,\n processor=[text_cleanup, normalize_state]\n )\n\nfetcher = MyFetcher(url=\"http://....\")\nfetcher.parse()\n\nfetcher._raw_data.state\n'Sao-Paulo'\nfetcher._data.state\n\n```\n\n#### Parse methods\n\nany method called ``parse_`` will run after all the process of selecting and parsing, it receives the selector or the value depending on auto_extract and takes_first argument in that field.\n\nexample:\n\n```python\ndef parse_name(self, selector):\n return selector.css('::text').extract()[0].upper()\n```\n\nIn the above case, the name field returns the raw_selector and in the parse method we can build extra queries using ``css`` or ``xpath`` and also we need to extract() the values from the selector and optionally select the first element and apply any transformation we need.\n\n### Caching the html fetch\n\nIn order to cache the html returned by the url fetching for future parsing and tests you specify a cache model, by default there is no cache but you can use the built in RedisCache passing\n\n```python\n from splinter_model import RedisCache\n fetcher = TestFetcher(cache_fetch=True,\n cache=RedisCache,\n cache_expire=1800)\n```\n\nor specifying arguments to the Redis client.\n\n> it is a general Redis connection from python ``redis`` module\n\n```python\n fetcher = TestFetcher(cache_fetch=True,\n cache=RedisCache(\"192.168.0.12:9200\"),\n cache_expire=1800)\n```\n\nYou can create your own caching structure, e.g: to cache htmls in memcached or s3\n\nthe cache class just need to implement ``get`` and ``set`` methods.\n\n```python\nfrom boto import connect_s3\n\nclass S3Cache(object):\n def __init__(self, *args, **kwargs):\n connection = connect_s3(ACCESS_KEY, SECRET_KEY)\n self.bucket = connection.get_bucket(BUCKET_ID)\n\n def get(self, key):\n value = self.bucket.get_key(key)\n return value.get_contents_as_string() if key else None\n\n def set(self, key, value, expire=None):\n self.bucket.set_contents(key, value, expire=expire)\n\n\nfetcher = MyFetcher(url=\"http://...\",\n cache_fetch=True,\n cache=S3cache,\n cache_expire=1800)\n\n```\n\n### Instalation\n\neasy to install\n\nIf running ubuntu maybe you need to run:\n\n```bash\nsudo apt-get install python-scrapy\nsudo apt-get install libffi-dev\nsudo apt-get install python-dev\n```\n\nthen\n\n```bash\npip install splinter_model\n```\n\nor\n\n\n```bash\ngit clone https://github.com/rochacbruno/splinter_model\ncd splinter_model\npip install -r requirements.txt\npython setup.py install\npython example.py\n```\n\nExample code to fetch the url http://en.m.wikipedia.org/wiki/Guido_van_Rossum\n\n```python\n#coding: utf-8\n\nfrom splinter_model import BaseFetcherModel, CSSField, XPathField\n\n\nclass TestFetcher(BaseFetcherModel):\n photo_url = XPathField('//*[@id=\"content\"]/div[1]/table/tr[2]/td/a')\n\n nationality = CSSField(\n '#content > div:nth-child(1) > table > tr:nth-child(4) > td > a',\n )\n\n links = CSSField(\n '#content > div:nth-child(11) > ul > li > a.external::attr(href)',\n auto_extract=True\n )\n\n def parse_photo_url(self, selector):\n return \"http://en.m.wikipedia.org/{}\".format(\n selector.xpath(\"@href\").extract()[0]\n )\n\n def parse_nationality(self, selector):\n return selector.css(\"::text\").extract()[0]\n\n def parse_name(self, selector):\n return selector.extract()[0]\n\n def pre_parse(self, selector=None):\n # this method is executed before the parsing\n # you can override it, take a look at the doc string\n\n def post_parse(self):\n # executed after all parsers\n # you can load any data on to self._data\n # access self._data and self._fields for current data\n # self.selector contains original page\n # self.fetch() returns original html\n self._data.url = self.url\n\n\nclass DummyModel(object):\n \"\"\"\n For tests only, it can be a model in your database ORM\n \"\"\"\n\n\nif __name__ == \"__main__\":\n from pprint import pprint\n\n fetcher = TestFetcher(cache_fetch=True)\n fetcher.url = \"http://en.m.wikipedia.org/wiki/Guido_van_Rossum\"\n\n # Mappings can be loaded from a json file\n # fetcher.load_mappings_from_file('path/to/file')\n fetcher.mappings['name'] = {\n \"css\": (\"#section_0::text\")\n }\n\n fetcher.parse()\n\n print \"Fetcher holds the data\"\n print fetcher._data.name\n print fetcher._data\n\n # How to populate an object\n print \"Populating an object\"\n dummy = DummyModel()\n\n fetcher.populate(dummy, fields=[\"name\", \"nationality\"])\n # fields attr is optional\n print dummy.nationality\n pprint(dummy.__dict__)\n\n```\n\n# outputs\n\n\n```\nFetcher holds the data\nGuido van Rossum\n{'links': [u'http://www.python.org/~guido/',\n u'http://neopythonic.blogspot.com/',\n u'http://www.artima.com/weblogs/index.jsp?blogger=guido',\n u'http://python-history.blogspot.com/',\n u'http://www.python.org/doc/essays/cp4e.html',\n u'http://www.twit.tv/floss11',\n u'http://www.computerworld.com.au/index.php/id;66665771',\n u'http://www.stanford.edu/class/ee380/Abstracts/081105.html',\n u'http://stanford-online.stanford.edu/courses/ee380/081105-ee380-300.asx'],\n 'name': u'Guido van Rossum',\n 'nationality': u'Dutch',\n 'photo_url': 'http://en.m.wikipedia.org//wiki/File:Guido_van_Rossum_OSCON_2006.jpg',\n 'url': 'http://en.m.wikipedia.org/wiki/Guido_van_Rossum'}\nPopulating an object\nDutch\n{'name': u'Guido van Rossum', 'nationality': u'Dutch'}\n```",
"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/rochacbruno/splinter_model",
"keywords": "splinter_model",
"license": "BSD",
"maintainer": null,
"maintainer_email": null,
"name": "splinter_model",
"package_url": "https://pypi.org/project/splinter_model/",
"platform": "UNKNOWN",
"project_url": "https://pypi.org/project/splinter_model/",
"project_urls": {
"Download": "UNKNOWN",
"Homepage": "https://github.com/rochacbruno/splinter_model"
},
"release_url": "https://pypi.org/project/splinter_model/0.1.6/",
"requires_dist": null,
"requires_python": null,
"summary": "Splinter helper to create scrapers from models",
"version": "0.1.6"
},
"last_serial": 1113302,
"releases": {
"0.1.6": []
},
"urls": []
}