### Install Morss Python Package (Simple)

Source: https://github.com/pictuga/morss/blob/master/README.md

Install the Morss Python package with only in-memory cache available. This method does not include optional dependencies like `lxml` or `gunicorn`.

```Shell
pip install morss
```

```Shell
pip install git+https://git.pictuga.com/pictuga/morss.git
```

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

### Run Morss with Docker Compose

Source: https://github.com/pictuga/morss/blob/master/README.md

This command starts Morss using a `docker-compose.yml` file, which is the recommended method for managing multi-container Docker applications.

```shell
docker-compose up
```

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

### Deploy Morss with Cloud-init on Ubuntu

Source: https://github.com/pictuga/morss/blob/master/README.md

This YAML configuration sets up a Ubuntu instance for Morss deployment, installing necessary Python packages, configuring environment variables for debugging and caching, and setting up a per-boot script to run the Morss daemon. It's suitable for cloud providers supporting `cloud-init`.

```yml
#cloud-config

packages:
  - python3-pip
  - python3-wheel
  - python3-lxml
  - python3-setproctitle
  - ca-certificates

write_files:
  - path: /etc/environment
    append: true
    content: |
      DEBUG=1
      CACHE=diskcache
      CACHE_SIZE=1073741824 # 1GiB
  - path: /var/lib/cloud/scripts/per-boot/morss.sh
    permissions: 744
    content: |
      #!/bin/sh
      /usr/local/bin/morss-helper daemon

runcmd:
  - source /etc/environment
  - update-ca-certificates
  - iptables -I INPUT 6 -m state --state NEW -p tcp --dport ${PORT:-8000} -j ACCEPT
  - netfilter-persistent save
  - pip install morss[full]
```

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

### Install Morss Python Package (Full)

Source: https://github.com/pictuga/morss/blob/master/README.md

Install the Morss Python package with all optional dependencies, including various cache backends and `gunicorn` for efficient HTTP handling. This provides the full feature set of Morss.

```Shell
pip install morss[full]
```

```Shell
pip install git+https://git.pictuga.com/pictuga/morss.git#egg=morss[full]
```

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

### Run Morss with Gunicorn

Source: https://github.com/pictuga/morss/blob/master/README.md

This command starts the Morss application using Gunicorn, a Python WSGI HTTP server, with the `--preload` option. Gunicorn is recommended for better performance in production environments.

```shell
gunicorn --preload morss
```

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

### Run Morss as a CLI Application

Source: https://github.com/pictuga/morss/blob/master/README.md

This command demonstrates how to use Morss as a command-line tool, allowing users to pass arguments and a feed URL directly.

```shell
morss [--argwithoutvalue] [--argwithvalue=value] [...] FEEDURL
```

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

### Run Morss with uWSGI

Source: https://github.com/pictuga/morss/blob/master/README.md

This command runs Morss using uWSGI, a fast application server, serving it via HTTP on port 8000 and loading `main.py` as the WSGI application.

```shell
uwsgi --http :8000 --plugin python --wsgi-file main.py
```

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

### Process RSS Feed with Caching and Options in morss

Source: https://github.com/pictuga/morss/blob/master/README.md

Illustrates how to use `morss.process` with a specified cache location and additional options. This example shows how to enable CSV output and store cached data.

```python
>>> import morss
>>> url = 'http://feeds.bbci.co.uk/news/rss.xml'
>>> cache = '/tmp/morss-cache' # diskcache cache location
>>> options = {'csv':True}
>>> xml_string = morss.process(url, cache, options)
>>> xml_string[:50]
'{"title": "BBC News - Home", "desc": "The latest s'
```

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

### Run Morss with Docker Compose (Recommended)

Source: https://github.com/pictuga/morss/blob/master/README.md

Configure and run Morss using Docker Compose, which is the recommended method for deployment. This snippet defines a service that exposes Morss on port 8000.

```YAML
services:
    app:
        image: pictuga/morss
        ports:
            - '8000:8000'
```

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

### Run Morss with Internal HTTP Server

Source: https://github.com/pictuga/morss/blob/master/README.md

This command starts Morss using its built-in, basic HTTP server, primarily for debugging purposes. It defaults to port 8000, which can be overridden by the `PORT` environment variable.

```shell
morss
```

```shell
PORT=9000 morss
```

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

### Retrieve Full-Text RSS Feed with morss.process

Source: https://github.com/pictuga/morss/blob/master/README.md

Demonstrates how to quickly fetch and process a full-text RSS feed using the `morss.process` function. It shows a basic import and usage, returning an XML string.

```python
>>> import morss
>>> xml_string = morss.process('http://feeds.bbci.co.uk/news/rss.xml')
>>> xml_string[:50]
"<?xml version='1.0' encoding='UTF-8'?>\n<?xml-style"
```

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

### Run Morss CLI via Docker

Source: https://github.com/pictuga/morss/blob/master/README.md

This command shows how to execute Morss as a CLI application within a Docker container, passing arguments and a feed URL.

```shell
docker run morss --clip http://feeds.bbci.co.uk/news/rss.xml
```

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

### Run Morss from Local Docker Image

Source: https://github.com/pictuga/morss/blob/master/README.md

This command runs a Docker image named `morss` (presumably built locally from source), mapping port 8000 from the container to the host.

```shell
docker run -p 8000:8000 morss
```

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

### Recommended File Structure for Apache/Nginx CGI

Source: https://github.com/pictuga/morss/blob/master/README.md

This snippet illustrates a suggested file organization for deploying Morss with `mod_cgi` or FastCGI on web servers like Apache or Nginx, separating the main script, Morss modules, and dependencies.

```APIDOC
/
├── cgi
│   │
│   ├── main.py
│   ├── morss
│   │   ├── __init__.py
│   │   ├── __main__.py
│   │   ├── morss.py
│   │   └── ...
│   │
│   ├── dateutil
│   └── ...
│
├── .htaccess
├── index.html
└── ...
```

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

### Build Morss Docker Image from Source (CLI)

Source: https://github.com/pictuga/morss/blob/master/README.md

Build the Morss Docker image directly from its Git repository using the Docker CLI. This ensures you have the latest development version or a custom build.

```Shell
docker build --tag morss https://git.pictuga.com/pictuga/morss.git --no-cache --pull
```

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

### Run Morss from Docker Hub

Source: https://github.com/pictuga/morss/blob/master/README.md

This command pulls and runs the `pictuga/morss` Docker image, mapping port 8000 from the container to the host, allowing Morss to be accessed via `localhost:8000`.

```shell
docker run -p 8000:8000 pictuga/morss
```

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

### Morss Configuration Environment Variable Reference

Source: https://github.com/pictuga/morss/blob/master/README.md

Comprehensive documentation of environment variables used to configure Morss behavior, including settings for debugging, SSL handling, HTTP timeouts, data paths, performance limits for feed parsing, and cache backend settings.

```APIDOC
Environment Variables:
  DEBUG:
    Type: Boolean (1 for true)
    Description: Enables script execution feedback for debugging purposes.
  IGNORE_SSL:
    Type: Boolean (1 for true)
    Description: Instructs Morss to ignore SSL certificates when fetching feeds and articles.
  DELAY:
    Type: Integer (seconds)
    Description: Sets the browser cache delay, applicable only for HTTP clients.
  TIMEOUT:
    Type: Integer (seconds)
    Description: Sets the HTTP timeout for fetching RSS feeds and articles.
  DATA_PATH:
    Type: String (file path)
    Description: Specifies a custom file location for the 'www' folder.
  MAX_TIME:
    Type: Integer (seconds)
    Description: Sets the maximum time spent fetching articles. Use -1 for unlimited. Older articles might still be taken from cache.
  MAX_ITEM:
    Type: Integer
    Description: Sets the maximum number of articles to fetch. Use -1 for unlimited. Additional articles may be taken from cache.
  LIM_TIME:
    Type: Integer (seconds)
    Description: Sets the maximum time spent processing a feed (fetched or cached). Articles exceeding this limit are dropped. Use -1 for unlimited.
  LIM_ITEM:
    Type: Integer
    Description: Sets the maximum number of articles checked, limiting both fetched and cached articles. Articles beyond this limit are dropped, even if cached. Use -1 for unlimited.
  CACHE:
    Type: String ('redis', 'diskcache', or empty/default)
    Description: Selects the cache backend. Default is a simple Python in-memory dict-like object.
  REDIS_HOST:
    Type: String
    Description: Redis host for 'redis' cache backend.
  REDIS_PORT:
    Type: Integer
    Description: Redis port for 'redis' cache backend.
  REDIS_DB:
    Type: Integer
    Description: Redis database number for 'redis' cache backend.
  REDIS_PWD:
    Type: String
    Description: Redis password for 'redis' cache backend.
  DISKCACHE_DIR:
    Type: String (directory path)
    Description: Target directory for 'diskcache' backend.
  CACHE_SIZE:
    Type: Integer
    Description: Target number of items in the cache. For 'diskcache', this is max size in Bytes. Defaults to 1k entries.
  CACHE_LIFESPAN:
    Type: Integer (seconds)
    Description: Frequency at which the cache is trimmed to CACHE_SIZE. Defaults to 1 minute.
  GUNICORN_CMD_ARGS:
    Type: String
    Description: Allows passing command line arguments directly to Gunicorn.
```

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

### Pull Morss Docker Image

Source: https://github.com/pictuga/morss/blob/master/README.md

Download the latest Morss Docker image from Docker Hub using the Docker CLI. This provides a pre-built containerized version of Morss.

```Shell
docker pull pictuga/morss
```

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

### Step-by-Step RSS Feed Processing with morss Functions

Source: https://github.com/pictuga/morss/blob/master/README.md

Shows a more granular control over the RSS feed processing by using individual `morss` functions: `morss.Options`, `morss.FeedFetch`, `morss.FeedGather`, and `morss.FeedFormat`. This allows for custom workflows and deeper control over the feed pipeline.

```python
import morss

url = 'http://newspaper.example/feed.xml'
options = morss.Options(csv=True) # arguments

url, rss = morss.FeedFetch(url, options) # this only grabs the RSS feed
rss = morss.FeedGather(rss, url, options) # this fills the feed and cleans it up

output = morss.FeedFormat(rss, options, 'unicode') # formats final feed
```

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

### HTTP 200 OK Response with Meta Refresh Redirect

Source: https://github.com/pictuga/morss/blob/master/tests/samples/meta-redirect-abs.txt

This snippet presents a complete HTTP 200 OK response, including standard headers and an HTML body. The HTML uses a <meta http-equiv="refresh"> tag to instruct the client browser to redirect to a specified URL after a 2-second delay, serving as a client-side redirection mechanism.

```HTTP
HTTP/1.1 200 OK
content-type: text/html; charset=UTF-8

<!DOCTYPE html>
<html>
<head><meta http-equiv="refresh" content="2; url = /200-ok.txt" /></head>
<body>meta redirect</body>
</html>
```

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

### morss Command Line Interface (CLI) Arguments

Source: https://github.com/pictuga/morss/blob/master/README.md

Documents the various command-line arguments available for the `morss` utility. It details options for input, output formatting, actions, custom feed parsing, and miscellaneous settings, providing a comprehensive reference for CLI usage.

```APIDOC
usage: morss [-h] [--post STRING] [--xpath XPATH]
             [--format {rss,json,html,csv}] [--search STRING] [--clip]
             [--indent] [--cache] [--force] [--proxy]
             [--order {first,last,newest,oldest}] [--firstlink] [--resolve]
             [--items XPATH] [--item_link XPATH] [--item_title XPATH]
             [--item_content XPATH] [--item_time XPATH]
             [--mode {xml,html,json}] [--nolink] [--noref] [--silent]
             url

Get full-text RSS feeds

positional arguments:
  url                   feed url

options:
  -h, --help            show this help message and exit
  --post STRING         POST request
  --xpath XPATH         xpath rule to manually detect the article

output:
  --format {rss,json,html,csv}
                        output format
  --search STRING       does a basic case-sensitive search in the feed
  --clip                stick the full article content under the original feed
                        content (useful for twitter)
  --indent              returns indented XML or JSON, takes more place, but
                        human-readable

action:
  --cache               only take articles from the cache (ie. don't grab new
                        articles' content), so as to save time
  --force               force refetch the rss feed and articles
  --proxy               doesn't fill the articles
  --order {first,last,newest,oldest}
                        order in which to process items (which are however NOT
                        sorted in the output)
  --firstlink           pull the first article mentioned in the description
                        instead of the default link
  --resolve             replace tracking links with direct links to articles
                        (not compatible with --proxy)

custom feeds:
  --items XPATH         (mandatory to activate the custom feeds function)
                        xpath rule to match all the RSS entries
  --item_link XPATH     xpath rule relative to items to point to the entry's
                        link
  --item_title XPATH    entry's title
  --item_content XPATH  entry's content
  --item_time XPATH     entry's date & time (accepts a wide range of time
                        formats)
  --mode {xml,html,json}
                        parser to use for the custom feeds

misc:
  --nolink              drop links, but keeps links' inner text
  --noref               drop items' link
  --silent              don't output the final RSS (useless on its own, but
                        can be nice when debugging)
```

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

### HTML Meta Refresh for Client-Side Redirection

Source: https://github.com/pictuga/morss/blob/master/tests/samples/meta-redirect-rel.txt

This HTML snippet shows how to implement a client-side redirect using the <meta http-equiv="refresh"> tag. The content attribute specifies the delay in seconds before redirection and the target URL.

```HTML
<!DOCTYPE html>
<html>
<head><meta http-equiv="refresh" content="2; url = ./200-ok.txt" /></head>
<body>meta redirect</body>
</html>
```

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

### Morss Server URL Structure

Source: https://github.com/pictuga/morss/blob/master/README.md

This defines the URL pattern for accessing Morss when running as a server. It shows how to specify optional arguments and the feed URL, with `main.py` being optional depending on server configuration.

```APIDOC
http://PATH/TO/MORSS/[main.py/][:argwithoutvalue[:argwithvalue=value[...]]]/FEEDURL

For example: http://morss.example/:clip/https://twitter.com/pictuga
```

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

### Setting Morss Environment Variables Across Platforms

Source: https://github.com/pictuga/morss/blob/master/README.md

This snippet demonstrates various methods for setting environment variables for the Morss application across different deployment environments, including Docker CLI, Docker Compose, Gunicorn/uWSGI/CLI, Apache, and cloud-init.

```bash
docker run -p 8000:8000 morss --env KEY=value
```

```yaml
services:
  morss:
    image: your_morss_image
    environment:
      - KEY=value
      - ANOTHER_KEY=another_value
```

```bash
KEY=value ANOTHER_KEY=another_value gunicorn morss_app:app
```

```apacheconf
<VirtualHost *>
    SetEnv KEY value
    SetEnv ANOTHER_KEY another_value
</VirtualHost>

# Or in .htaccess:
# SetEnv KEY value
```

```bash
# /etc/environment
KEY="value"
ANOTHER_KEY="another_value"
```

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

### Use Morss as Liferea Newsreader Hook

Source: https://github.com/pictuga/morss/blob/master/README.md

This command illustrates how to integrate Morss with the Liferea newsreader as a custom script, allowing Liferea to process RSS feeds through Morss's functionality.

```shell
morss [--argwithoutvalue] [--argwithvalue=value] [...] FEEDURL
```

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

### Build Morss Docker Image from Source with Docker Compose

Source: https://github.com/pictuga/morss/blob/master/README.md

Build the Morss Docker image from its Git repository using Docker Compose. This method integrates the build process into your Docker Compose workflow, followed by executing the build command.

```YAML
services:
    app:
        build: https://git.pictuga.com/pictuga/morss.git
        image: morss
        ports:
            - '8000:8000'
```

```Shell
docker-compose build --no-cache --pull
```

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

### morss HTTP-Only API Options

Source: https://github.com/pictuga/morss/blob/master/README.md

Describes additional HTTP-specific options that can be used with morss, such as `callback` for JSONP, `cors` for cross-origin resource sharing, and `txt` for changing the content-type to plain text for faster viewing.

```APIDOC
callback=NAME: for JSONP calls
cors: allow Cross-origin resource sharing (allows XHR calls from other
servers)
txt: changes the http content-type to txt (for faster "view-source:")
```

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

### Apache .htaccess Configuration for Morss CGI

Source: https://github.com/pictuga/morss/blob/master/README.md

This `.htaccess` file configures Apache for Morss, enabling CGI execution for `main.py`, setting environment variables for debugging, and denying access to sensitive files. It also defines a custom 404 error document.

```htaccess
Options -Indexes

ErrorDocument 404 /cgi/main.py

# Turn debug on for all requests
SetEnv DEBUG 1

# Turn debug on for requests with :debug in the url
SetEnvIf Request_URI :debug DEBUG=1

<Files ~ "\.(py|pyc|db|log)$">
	deny from all
</Files>

<Files main.py>
	allow from all
	AddHandler cgi-script .py
	Options +ExecCGI
</Files>
```

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

### Example Atom 0.3 Feed XML Structure

Source: https://github.com/pictuga/morss/blob/master/tests/samples/feed-atom03-utf-8.txt

This snippet illustrates the basic XML structure for an Atom 0.3 feed. It includes the feed's title and subtitle, along with a single entry containing placeholders for item title, link, summary, content, and an issued timestamp.

```XML
<?xml version='1.0' encoding='utf-8' ?>
<feed version='0.3' xmlns='http://purl.org/atom/ns#'>
	<title>!TITLE!</title>
	<subtitle>!DESC!</subtitle>
	<entry>
		<title>!ITEM_TITLE!</title>
		<link rel='alternate' type='text/html' href='!ITEM_LINK!' />
		<summary>!ITEM_DESC!</summary>
		<content>!ITEM_CONTENT!</content>
		<issued>2022-01-01T00:00:01+01:00</issued> <!-- FIXME -->
	</entry>
</feed>
```

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

### Example RSS 2.0 Feed XML Template

Source: https://github.com/pictuga/morss/blob/master/tests/samples/feed-rss-channel-utf-8.txt

This XML snippet defines the basic structure of an RSS 2.0 feed. It includes a root 'rss' element, a 'channel' with title and description, and an 'item' with common fields like title, publication date, link, description, and encoded content. Placeholders (e.g., !TITLE!) indicate where dynamic data would be inserted.

```XML
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version='1.0' encoding='utf-8'?>
<rss xmlns:content="http://purl.org/rss/1.0/modules/content/" version="2.0">
  <channel>
    <title>!TITLE!</title>
    <description>!DESC!</description>
    <item>
      <title>!ITEM_TITLE!</title>
      <pubDate>Mon, 01 Jan 2022 00:00:01 +0100</pubDate>
      <link>!ITEM_LINK!</link>
      <description>!ITEM_DESC!</description>
      <content:encoded>!ITEM_CONTENT!</content:encoded>
    </item>
  </channel>
</rss>
```

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

### Basic HTML Page Structure Template

Source: https://github.com/pictuga/morss/blob/master/tests/samples/feed-html-utf-8.txt

This HTML snippet defines a foundational web page structure. It includes a header section for a main title and description, and a content area designed to display a single item, complete with a link, title, description, and detailed content. This template is suitable for dynamic content generation, where placeholders like !TITLE! and !ITEM_LINK! would be replaced.

```HTML
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<html>
<head></head>

<body>
<div id="header">
	<h1>!TITLE!</h1>
	<p>!DESC!</p>
</div>

<div id="content">
	<div class="item">
		<a target="_blank" href="!ITEM_LINK!">!ITEM_TITLE!</a>
		<div class="desc">!ITEM_DESC!</div>
		<div class="content">!ITEM_CONTENT!</div>
	</div>
</div>

</body>
</html>
```

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

### HTTP 200 OK Response with HTML Meta Redirect

Source: https://github.com/pictuga/morss/blob/master/tests/samples/alternate-abs.txt

This snippet demonstrates a successful HTTP 200 OK response. It includes standard HTTP headers like `content-type` and an HTML body. The HTML body contains a `<link>` tag for an RSS feed and the text 'meta redirect' within the `<body>` tag, indicating a potential redirect mechanism.

```HTTP
HTTP/1.1 200 OK
content-type: text/html; charset=UTF-8

<!DOCTYPE html>
<html>
<head><link rel="alternate" type="application/rss+xml" href="/200-ok.txt" /></head>
<body>meta redirect</body>
</html>
```

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

### Atom 1.0 Feed XML Structure Template

Source: https://github.com/pictuga/morss/blob/master/tests/samples/feed-atom-utf-8.txt

This XML snippet defines the basic structure of an Atom 1.0 feed. It includes root elements like 'feed', 'title', 'subtitle', and an 'entry' element with 'title', 'summary', 'content', 'link', 'updated', and 'published' tags. Placeholders like '!TITLE!' and '!ITEM_LINK!' indicate where dynamic data should be inserted for feed generation.

```XML
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns="http://www.w3.org/2005/Atom">
	<title>!TITLE!</title>
	<subtitle>!DESC!</subtitle>
	<entry>
		<title>!ITEM_TITLE!</title>
		<summary>!ITEM_DESC!</summary>
		<content type="html">!ITEM_CONTENT!</content>
		<link href="!ITEM_LINK!"/>
		<updated>2022-01-01T00:00:01+01:00</updated>
		<published>2022-01-01T00:00:02+01:00</published>
	</entry>
</feed>
```

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

### HTML Meta Refresh Client-Side Redirect

Source: https://github.com/pictuga/morss/blob/master/tests/samples/meta-redirect-url.txt

This HTML snippet demonstrates how to perform a client-side redirect using the `<meta http-equiv="refresh">` tag. It specifies a delay (2 seconds) and a target URL for the redirection. This method is often used for simple redirects or splash pages, but server-side redirects are generally preferred for SEO and accessibility.

```HTML
<!DOCTYPE html>\n<html>\n<head><meta http-equiv=\"refresh\" content=\"2; url = http://localhost:8888/200-ok.txt\" /></head>\n<body>meta redirect</body>\n</html>
```

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

### Basic CSS Styling for Body and Input Elements

Source: https://github.com/pictuga/morss/blob/master/www/index.html

This CSS snippet provides basic styling for the `body` and `input` HTML elements. It centers content, sets margins, and defines minimum/maximum widths for the body, while making input fields block-level and centered with automatic margins.

```CSS
body { padding : 2%; margin : auto; margin-top : 10px; margin-bottom : 10px; min-width: 70%; max-width: 70px; text-align : center; } input { display: block; min-width: 50%; margin: auto; margin-top: 1em; text-align : center; }
```

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

### JavaScript Form Submission Handler for URL Redirection

Source: https://github.com/pictuga/morss/blob/master/www/index.html

This JavaScript code attaches an event listener to the first form on the page. On submission, it prevents the default form action, extracts a URL from the first form element, removes 'http(s)://' prefixes, and redirects the browser to a new path constructed from the cleaned URL.

```JavaScript
form = document.forms[0]
form.addEventListener('submit', function(e) {
  console.log('lol');
  url = form.elements[0].value.replace(/^https?:\\/\\/?/, '')
  document.location = "./" + url;
  e.preventDefault();
});
```

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

### Morss API Standard JSON Response Structure

Source: https://github.com/pictuga/morss/blob/master/tests/samples/feed-json-utf-8.txt

This snippet illustrates the typical JSON response body returned by the Morss API. The response includes a main 'title' and 'desc' for the overall feed, and an 'items' array containing individual entries. Each item object provides details such as its 'title', 'time' (timestamp), 'url', 'desc' (description), and 'content'.

```json
{
	"title": "!TITLE!",
	"desc": "!DESC!",
	"items": [
		{
			"title": "!ITEM_TITLE!",
			"time": "2022-01-01T00:00:01+0100",
			"url": "!ITEM_LINK!",
			"desc": "!ITEM_DESC!",
			"content": "!ITEM_CONTENT!"
		}
	]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.