Metadata-Version: 2.4
Name: facrawlio
Version: 0.2.0
Summary: Easy one-function web scraping to CSV or JSON
Author-email: Fahad Hameed <dr.fahad1001@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/DSFAHAD/facrawlio
Project-URL: Repository, https://github.com/DSFAHAD/facrawlio
Keywords: web scraping,scraper,csv,json,beautifulsoup
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25
Requires-Dist: beautifulsoup4>=4.10
Requires-Dist: lxml>=4.6

# facrawlio

Easy one-function web scraping — pull data from any page and save it straight to CSV or JSON.

## Install

```bash
pip install -e .
```

(or, once published: `pip install facrawlio`)

## Quick start

```python
from facrawlio import scrape

# Scrape into CSV
data = scrape(
    url="https://example.com/products",
    selector=".product-card",      # the repeating element for each item
    fields={
        "title": "h2",
        "price": ".price",
        "link": "a::attr(href)"    # use ::attr(x) to grab an attribute
    },
    output="products.csv"
)

# Same call, just change the output filename to get JSON instead
data = scrape(
    url="https://example.com/products",
    selector=".product-card",
    fields={"title": "h2", "price": ".price"},
    output="products.json"
)

print(data)  # list[dict] — also written to the output file
```

## No `fields`? Just grab text

```python
from facrawlio import scrape

headlines = scrape(
    url="https://example.com/news",
    selector="h2.headline",
    output="headlines.json"
)
# [{"text": "..."}, {"text": "..."}, ...]
```

## Parameters

| Param         | Type   | Description                                                              |
|---------------|--------|----------------------------------------------------------------------------|
| `url`         | str    | Page to scrape                                                            |
| `selector`    | str    | CSS selector for each repeating item                                     |
| `fields`      | dict   | `{column_name: sub_selector}`; use `::attr(name)` for attributes         |
| `output`      | str    | Filename ending in `.csv` or `.json`; `None` to skip saving               |
| `method`      | str    | `"GET"` or `"POST"`                                                       |
| `headers`     | dict   | Extra request headers                                                    |
| `params`      | dict   | URL query params                                                         |
| `data`        | dict   | POST form data                                                           |
| `timeout`     | int    | Request timeout in seconds (default 10)                                  |
| `delay`       | float  | Seconds to sleep before requesting (basic rate limiting)                 |
| `return_data` | bool   | Return the scraped list (default `True`)                                 |

## Notes

- Respect `robots.txt` and each site's terms of service before scraping.
- Add a `delay` when scraping multiple pages in a loop to be polite to servers.
- This library only fetches static HTML — it does not execute JavaScript. For JS-heavy sites you'll need a browser-based tool like Selenium or Playwright.

## License

MIT
