README.rst

Fodio Home Page

What is fodio?

Fodio is a web scraping tool, used to easily traverse websites and collects data on. Some key concepts fodio was built on was simplicity and asynchronous-ity (No, I don't think that's a real word). Inspired by the Demiurge library, which is not active anymore, Fodio is here to save the day!

Why would I not use Scrapy?

Good Question! There are some key differences that are important too note.

1. Scrapy uses C extensions, which depending on the environment, can be a pain!
2. Scrapy is not asynchronous!
3. IMO, This is simpler.

Also, if you're on linux, you can use uvloop, which should help speed things up!

Installation

To install with pypi, use simply pip install fodio

To install manually, either download and unpack, or clone this repository. Then, while in the root of the local repository, do python setup.py install

I'm not great at this documentaion thing, so let's just get right into the quick-start.

Quick-Start

Too start scraping, inspect element will be your friend. You're going to be copying the CSS selectors in the elements you wish to harvest. In this case, we'll be walking though a github example that you can also find in the demo file, on the Fodio github page.

First, we need to make an item. Then "item" will represent a section of the page.

It's good too note, that this example won't have Items as ItemAttrs, but you can do that. I really suggest looking at the demos file, because that includes a bunch of great examples on what to do.

class GithubPage(Item):
    ...
    class Meta:
        ...

Notice the "Meta" class. This is used too hold your selector and root_url information. In this senerio, we want to get a github user's real name + description. First, let's narrow in on the profile card with the ".h-card" selector. Then, we'll supply the root_url "https://github.com"

class GithubPage(Item):
    ...
    class Meta:
        selector = ".h-card"
        root_url = "https://github.com"

Not that bad eh? Now that we have the profile card, we need to set some ItemAttributes to extract the information. We'll use a TextAttr object to extract the text from a node with the real name, and anther TextAttr for the description.

class GithubPage(Item):
    name = TextAttr(".p-name")
    desc = TextAttr(".p-note > div:nth-child(1)", raise_not_found=False)

    class Meta:
        selector = ".h-card"
        root_url = "https://github.com"

Note

Notice the raise_not_found kwarg. Some github profiles don't have a description, and we don't want it too raise an error if they don't. The same if True for the real name, however that element will exist if they have a real name or not, so we'll have to check manually.

Now time too run it! we'll create an asynchronous function called runner to do this. GithubPage has a classmethod called search which will add a path too the root_url, and fetch it. So let's do that.

accounts = ['Zwork101', 'bukson', 'torvalds', 'User1m', 'random-robbie']
async def runner():
    result = await GithubPage.search(account)
    print("{account_name}'s real name is {real_name}".format(
        account_name=account, real_name=result['name'] if result['name'] else "not known"))
    print('{description}\n'.format(
        description=('"' + result['desc'] + '"') if result['desc'] else "No Description"))

And we're done! After adding asyncio too run it, this is our final product:

import asyncio

from fodio import Item, TextAttr


class GithubPage(Item):
        name = TextAttr(".p-name")
        desc = TextAttr(".p-note > div:nth-child(1)", raise_not_found=False)

        class Meta:
            selector = ".h-card"
            root_url = "https://github.com"

accounts = ['Zwork101', 'bukson', 'torvalds', 'User1m', 'random-robbie']

async def runner():
    result = await GithubPage.search(account)
    print("{account_name}'s real name is {real_name}".format(
        account_name=account, real_name=result['name'] if result['name'] else "not known"))
    print('{description}\n'.format(
        description=('"' + result['desc'] + '"') if result['desc'] else "No Description"))

loop = asyncio.get_event_loop()
loop.run_until_complete(runner())

That wasn't that bad now was it? For more examples, see the demo folder. Otherwise, get scraping!

Wait, but why is it called "Fodio"

Well, apparently developers like to name their projects in latin, or some other language no one uses. Fodio (atleast this is what some sites said) can mean "delve" which is an english word for all you non-english majors / non-Magic: The Gathering players. Delve means to research and dig, 2 things this library does!