Metadata-Version: 2.4
Name: newsheadlines
Version: 0.0.3
Summary: Latest news headlines fetcher from major sources
Author-email: Theo Maillard <theomaillard11@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/theomaillard/newsheadlines
Keywords: news,headlines
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4
Requires-Dist: requests-cache
Dynamic: license-file

# newsheadlines

Python package to fetch the latest news headlines from major news outlets by parsing their webpages.

> ℹ️ Every response is cached for 10 minutes before a new request is made.

## Installation

The latest version can be installed via pip:

```shell
pip install newsheadlines
```

## Documentation

### `class Headline`

A dataclass representing a single news headline.

| Field    | Type          | Description                            |
| -------- | ------------- | -------------------------------------- |
| `title`  | `str`         | The headline text                      |
| `source` | `str`         | Source identifier (e.g. `"bbc"`)       |
| `url`    | `str \| None` | Link to the full article, if available |

### `newsheadlines.all(source_name)`

Returns a list of all `Headline` objects from the given source.

#### **Parameters**

- `source_name (str)` - one of the supported source keys (case-insensitive)

#### **Returns**

- `list[Headline]`

#### **Example**

```python
import newsheadlines

headlines = newsheadlines.all("bbc")

for h in headlines:
    print(h.title)
    print(h.url)
    print(h.source)
```

### `newsheadlines.main(source_name)`

Returns only the top/main Headline from the given source.

#### **Parameters**

- `source_name (str)` - one of the supported source keys (case-insensitive)

#### **Returns**

- `Headline`

#### **Example**

```python
import newsheadlines

headline = newsheadlines.main("bbc")

print(headline.title)
print(headline.url)
print(headline.source)
```

## Available sources

|       Key       |                          Source                           |
| :-------------: | :-------------------------------------------------------: |
|   `"apnews"`    |              [AP News](https://apnews.com/)               |
|     `"bbc"`     |           [BBC News](https://www.bbc.com/news)            |
|     `"cnn"`     |              [CNN](https://edition.cnn.com/)              |
|     `"nyt"`     |      [The New York Times](https://www.nytimes.com/)       |
| `"theguardian"` | [The Guardian](https://www.theguardian.com/international) |
