podcastparser

https://podcastparser.readthedocs.io/
Admin
podcastparser is a simple and fast podcast feed parser library in Python that parses RSS 2.0 and...
Tokens:5,381
Snippets:45
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Get file basename without extension

Source: https://podcastparser.readthedocs.io

Extracts the filename portion without its extension.

```python
>>> file_basename_no_extension('/home/me/file.txt')
'file'
```

```python
>>> file_basename_no_extension('file')
'file'
```

--------------------------------

### Exceptions

Source: https://podcastparser.readthedocs.io

Custom exceptions raised by the podcastparser module.

```APIDOC
## FeedParseError /websites/podcastparser_readthedocs_io

### Description
Exception raised when attempting to parse an invalid feed.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **msg** (string) - Error message.
- **exception** (Exception) - The underlying exception.
- **locator** (object) - Locator information.

### Response
#### Success Response (200)
- **object** - The FeedParseError exception object.

### Response Example
```json
{
  "message": "Invalid feed format",
  "exception_type": "XMLParseError"
}
```
```

--------------------------------

### Parse a podcast feed with podcastparser

Source: https://podcastparser.readthedocs.io

Uses the parse function to process a feed URL and its corresponding file-like object. The result is returned as a dictionary.

```python
import podcastparser
import urllib.request

feedurl = 'http://example.com/feed.xml'

parsed = podcastparser.parse(feedurl, urllib.request.urlopen(feedurl))

# parsed is a dict
import pprint
pprint.pprint(parsed)
```

--------------------------------

### Podcast Parsing Functions

Source: https://podcastparser.readthedocs.io

Functions for parsing podcast feeds and related data.

```APIDOC
## parse /websites/podcastparser_readthedocs_io

### Description
Parses a podcast feed from the given URL and stream.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the feed. Will be used to resolve relative links.
- **stream** (file-like object) - Required - File-like object containing the feed content.
- **max_episodes** (integer) - Optional - Maximum number of episodes to return. 0 (default) means no limit.

### Response
#### Success Response (200)
- **dict** - A dictionary with the parsed contents of the feed.

### Request Example
```json
{
  "url": "http://example.com/podcast.rss",
  "stream": "<file-like object>",
  "max_episodes": 10
}
```

### Response Example
```json
{
  "title": "Example Podcast",
  "episodes": [
    {
      "title": "Episode 1",
      "published": "Fri, 21 Nov 1997 09:55:06 -0600"
    }
  ]
}
```
```

```APIDOC
## parse_length /websites/podcastparser_readthedocs_io

### Description
Parses a file length string into an integer.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **text** (string) - The string representing the file length.

### Request Example
```json
{
  "text": "100MB"
}
```

### Response
#### Success Response (200)
- **integer** - The parsed file length in bytes, or -1 if parsing fails.

### Response Example
```json
100000000
```
```

```APIDOC
## parse_pubdate /websites/podcastparser_readthedocs_io

### Description
Parses a date string into a Unix timestamp.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **text** (string) - The date string to parse.

### Request Example
```json
{
  "text": "Fri, 21 Nov 1997 09:55:06 -0600"
}
```

### Response
#### Success Response (200)
- **integer** - The Unix timestamp, or 0 if parsing fails.

### Response Example
```json
880127706
```
```

```APIDOC
## parse_time /websites/podcastparser_readthedocs_io

### Description
Parses a time string into seconds, following RFC2326, 3.6.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **value** (string) - The time string to parse (e.g., HH:MM:SS).

### Request Example
```json
{
  "value": "01:02:03"
}
```

### Response
#### Success Response (200)
- **integer** - The time in seconds.

### Response Example
```json
3723
```
```

```APIDOC
## parse_type /websites/podcastparser_readthedocs_io

### Description
Normalizes a MIME type string.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **text** (string) - The MIME type string to normalize.

### Request Example
```json
{
  "text": "text/plain"
}
```

### Response
#### Success Response (200)
- **string** - The normalized MIME type.

### Response Example
```json
"text/plain"
```
```

--------------------------------

### Data Structures

Source: https://podcastparser.readthedocs.io

Data structures used by the podcastparser module.

```APIDOC
## RSSItemDescription /websites/podcastparser_readthedocs_io

### Description
Represents the description of an RSS item, using a heuristic to prioritize content sources.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **description** (string) - The plain text description.
- **description_html** (string) - The HTML description.
- **content_encoded** (string) - Content encoded field.
- **itunes_summary** (string) - iTunes summary field.

### Response
#### Success Response (200)
- **object** - An RSSItemDescription object.

### Response Example
```json
{
  "description": "Short text description.",
  "description_html": "<p>HTML description.</p>"
}
```
```

--------------------------------

### Parse publication dates

Source: https://podcastparser.readthedocs.io

Converts various date string formats into a Unix timestamp. Returns 0 for empty or unknown strings.

```python
>>> parse_pubdate('Fri, 21 Nov 1997 09:55:06 -0600')
880127706
```

```python
>>> parse_pubdate('2003-12-13T00:00:00+02:00')
1071266400
```

```python
>>> parse_pubdate('2003-12-13T18:30:02Z')
1071340202
```

```python
>>> parse_pubdate('Mon, 02 May 1960 09:05:01 +0100')
-305049299
```

```python
>>> parse_pubdate('')
0
```

```python
>>> parse_pubdate('unknown')
0
```

--------------------------------

### URL and Text Utility Functions

Source: https://podcastparser.readthedocs.io

Functions for normalizing URLs and processing text content.

```APIDOC
## normalize_feed_url /websites/podcastparser_readthedocs_io

### Description
Normalizes and converts a URL for podcast feeds. Handles various schemes and formats.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **url** (string) - The URL to normalize.

### Request Example
```json
{
  "url": "itpc://example.org/podcast.rss"
}
```

### Response
#### Success Response (200)
- **string** - The normalized URL, or None if the URL is invalid.

### Response Example
```json
"http://example.org/podcast.rss"
```
```

```APIDOC
## file_basename_no_extension /websites/podcastparser_readthedocs_io

### Description
Returns the base name of a filename without its extension.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **filename** (string) - The filename to process.

### Request Example
```json
{
  "filename": "/home/me/file.txt"
}
```

### Response
#### Success Response (200)
- **string** - The filename without the extension.

### Response Example
```json
"file"
```
```

```APIDOC
## is_html /websites/podcastparser_readthedocs_io

### Description
Heuristically determines if a given text string appears to be HTML.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **text** (string) - The text to check.

### Request Example
```json
{
  "text": "<h1>HELLO</h1>"
}
```

### Response
#### Success Response (200)
- **boolean** - True if the text is likely HTML, False otherwise.

### Response Example
```json
true
```
```

```APIDOC
## remove_html_tags /websites/podcastparser_readthedocs_io

### Description
Removes HTML tags from a string and decodes HTML entities.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **html** (string) - The HTML string to process.

### Request Example
```json
{
  "html": "<p>This is <b>bold</b> text.</p>"
}
```

### Response
#### Success Response (200)
- **string** - The string with HTML tags removed.

### Response Example
```json
"This is bold text."
```
```

```APIDOC
## squash_whitespace /websites/podcastparser_readthedocs_io

### Description
Combines multiple whitespace characters into a single space and trims leading/trailing spaces.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **text** (string) - The text to process.

### Request Example
```json
{
  "text": "  some   text  with   spaces  "
}
```

### Response
#### Success Response (200)
- **string** - The text with squashed whitespace.

### Response Example
```json
"some text with spaces"
```
```

```APIDOC
## squash_whitespace_not_nl /websites/podcastparser_readthedocs_io

### Description
Combines multiple whitespace characters into a single space, but preserves linefeeds and carriage returns.

### Method
POST

### Endpoint
/websites/podcastparser_readthedocs_io

### Parameters
#### Request Body
- **text** (string) - The text to process.

### Request Example
```json
{
  "text": "linefeeds\ncarriage\r  returns"
}
```

### Response
#### Success Response (200)
- **string** - The text with squashed whitespace, preserving newlines.

### Response Example
```json
"linefeeds\ncarriage\r returns"
```
```

--------------------------------

### Normalize feed URLs

Source: https://podcastparser.readthedocs.io

Converts various URL formats into a standard HTTP URL. Returns None for invalid or unsupported schemes.

```python
>>> normalize_feed_url('itpc://example.org/podcast.rss')
'http://example.org/podcast.rss'
```

```python
>>> normalize_feed_url('curry.com')
'http://curry.com/'
```

```python
>>> normalize_feed_url('http://Example.COM/')
'http://example.com/'
```

```python
>>> normalize_feed_url('http://example.org/test?')
'http://example.org/test'
```

```python
>>> normalize_feed_url(' http://example.com/podcast.rss ')
'http://example.com/podcast.rss'
```

```python
>>> normalize_feed_url('http://') is None
True
```

```python
>>> normalize_feed_url('gopher://gopher.hprc.utoronto.ca/file.txt') is None
True
```

--------------------------------

### Atom Feed Elements

Source: https://podcastparser.readthedocs.io

Details the supported elements within an Atom feed for podcast parsing.

```APIDOC
## Atom Feed Elements

### Podcast Level Elements

- **atom:feed/atom:title** (string) - Podcast title (whitespace is squashed).
- **atom:feed/atom:subtitle** (string) - Podcast description (whitespace is squashed).
- **atom:feed/atom:icon** (string) - Podcast cover art.
- **atom:feed/atom:link@href** (string) - Podcast website.

### Episode Level Elements

- **atom:feed/atom:entry/atom:id** (string) - Episode unique identifier (GUID), mandatory.
- **atom:feed/atom:entry/atom:title** (string) - Episode title (whitespace is squashed).
- **atom:feed/atom:entry/atom:link@rel=enclosure** (string) - File download URL (@href), size (@length) and mime type (@type).
- **atom:feed/atom:entry/atom:link@rel=(self|alternate)** (string) - Episode website.
- **atom:feed/atom:entry/atom:link@rel=payment** (string) - Episode payment URL (e.g. Flattr).
- **atom:feed/atom:entry/atom:content** (string) - Episode description (in HTML or plaintext).
- **atom:feed/atom:entry/atom:published** (string) - Episode publication date.
- **atom:feed/atom:entry/media:thumbnail** (string) - Episode art URL.
- **atom:feed/atom:entry/media:group/media:thumbnail** (string) - Episode art URL.
- **atom:feed/atom:entry/psc:chapters** (object) - Podlove Simple Chapters, version 1.1 and 1.2.
  - **atom:feed/atom:entry/psc:chapters/psc:chapter** (object) - Chapter entry (@start, @title, @href and @image).
```

--------------------------------

### RSS Feed Elements

Source: https://podcastparser.readthedocs.io

Details the supported elements within an RSS feed for podcast parsing.

```APIDOC
## RSS Feed Elements

### Podcast Level Elements

- **rss@xml:base** (string) - Base URL for all relative links in the RSS file.
- **rss/channel/title** (string) - Podcast title (whitespace is squashed).
- **rss/channel/link** (string) - Podcast website.
- **rss/channel/description** (string) - Podcast description (whitespace is squashed).
- **rss/channel/image/url** (string) - Podcast cover art.
- **rss/channel/itunes:image** (string) - Podcast cover art (alternative).
- **rss/channel/itunes:type** (string) - Podcast type (whitespace is squashed). One of ‘episodic’ or ‘serial’.
- **rss/channel/atom:link@rel=payment** (string) - Podcast payment URL (e.g. Flattr).
- **rss/channel/generator** (string) - A string indicating the program used to generate the channel.
- **rss/channel/language** (string) - Podcast language.
- **rss/channel/itunes:author** (string) - The group responsible for creating the show.
- **rss/channel/itunes:owner** (string) - The podcast owner contact information.
- **rss/channel/itunes:category** (string) - The show category information.
- **rss/channel/itunes:explicit** (string) - Indicates whether podcast contains explicit material.
- **rss/channel/itunes:new-feed-url** (string) - The new podcast RSS Feed URL.
- **rss/redirect/newLocation** (string) - The new podcast RSS Feed URL.

### Episode Level Elements

- **rss/channel/item/guid** (string) - Episode unique identifier (GUID), mandatory.
- **rss/channel/item/title** (string) - Episode title (whitespace is squashed).
- **rss/channel/item/link** (string) - Episode website.
- **rss/channel/item/description** (string) - Episode description. If it contains html, it’s returned as description_html. Otherwise it’s returned as description (whitespace is squashed).
- **rss/channel/item/itunes:summary** (string) - Episode description (whitespace is squashed).
- **rss/channel/item/itunes:subtitle** (string) - Episode subtitled / one-line description (whitespace is squashed).
- **rss/channel/item/content:encoded** (string) - Episode description in HTML.
- **rss/channel/item/itunes:duration** (string) - Episode duration.
- **rss/channel/item/pubDate** (string) - Episode publication date.
- **rss/channel/item/atom:link@rel=payment** (string) - Episode payment URL (e.g. Flattr).
- **rss/channel/item/atom:link@rel=enclosure** (string) - File download URL (@href), size (@length) and mime type (@type).
- **rss/channel/item/itunes:image** (string) - Episode art URL.
- **rss/channel/item/media:thumbnail** (string) - Episode art URL.
- **rss/channel/item/media:group/media:thumbnail** (string) - Episode art URL.
- **rss/channel/item/media:content** (string) - File download URL (@url), size (@fileSize) and mime type (@type).
- **rss/channel/item/media:group/media:content** (string) - File download URL (@url), size (@fileSize) and mime type (@type).
- **rss/channel/item/enclosure** (string) - File download URL (@url), size (@length) and mime type (@type).
- **rss/channel/item/psc:chapters** (object) - Podlove Simple Chapters, version 1.1 and 1.2.
  - **rss/channel/item/psc:chapters/psc:chapter** (object) - Chapter entry (@start, @title, @href and @image).
- **rss/channel/item/itunes:explicit** (string) - Indicates whether episode contains explicit material.
- **rss/channel/item/itunes:author** (string) - The group responsible for creating the episode.
- **rss/channel/item/itunes:episode** (string) - An episode number.
- **rss/channel/item/itunes:episodeType** (string) - The episode type. This flag is used if an episode is a trailer or bonus content.
```

--------------------------------

### Parse time strings

Source: https://podcastparser.readthedocs.io

Converts time strings (HH:MM:SS.FRACT) into total seconds.

```python
>>> parse_time('0')
0
>>> parse_time('128')
128
>>> parse_time('00:00')
0
>>> parse_time('00:00:00')
0
>>> parse_time('00:20')
20
>>> parse_time('00:00:20')
20
>>> parse_time('01:00:00')
3600
>>> parse_time(' 03:02:01')
10921
>>> parse_time('61:08')
3668
>>> parse_time('25:03:30 ')
90210
>>> parse_time('25:3:30')
90210
>>> parse_time('61.08')
61
>>> parse_time('01:02:03.500')
3723
>>> parse_time(' ')
0
```

--------------------------------

### Parse file length

Source: https://podcastparser.readthedocs.io

Converts a string representation of file length into an integer. Returns -1 for invalid or unknown inputs.

```python
>>> parse_length(None)
-1
```

```python
>>> parse_length('0')
-1
```

```python
>>> parse_length('unknown')
-1
```

```python
>>> parse_length('100')
100
```

--------------------------------

### Squash whitespace

Source: https://podcastparser.readthedocs.io

Reduces multiple whitespace characters to a single space and trims leading/trailing whitespace.

```python
>>> squash_whitespace(' some           text  with a    lot of   spaces ')
'some text with a lot of spaces'
```

--------------------------------

### Squash whitespace excluding linefeeds

Source: https://podcastparser.readthedocs.io

Similar to squash_whitespace, but preserves linefeeds and carriage returns.

```python
>>> squash_whitespace_not_nl(' linefeeds\ncarriage\r  returns')
'linefeeds\ncarriage\r returns'
```

--------------------------------

### Normalize MIME types

Source: https://podcastparser.readthedocs.io

Normalizes MIME type strings, defaulting to 'application/octet-stream' for invalid or empty inputs.

```python
>>> parse_type('text/plain')
'text/plain'
```

```python
>>> parse_type('text')
'application/octet-stream'
```

```python
>>> parse_type('')
'application/octet-stream'
```

```python
>>> parse_type(None)
'application/octet-stream'
```
Tokens:
Raw