You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/modules/overview.rst
+38-7Lines changed: 38 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,19 +36,25 @@ A feed is represented by a ``Source`` object which has (among other things) a ``
36
36
37
37
To start reading a feed, simply create a new ``Source`` with the desired ``feed_url``
38
38
39
-
``Sources`` have ``Posts`` a which contain the content.
39
+
``Source`` objects have ``Post`` children which contain the content.
40
40
41
-
``Posts`` may have ``Enclosures`` s which is what podcasts use to send their audio. The app does not download enclosures, if you want to do that you will need to it in your project using the url provided.
41
+
A ``Post`` may have ``Enclosure`` (or more) which is what podcasts use to send their audio.
42
+
The app does not download enclosures, if you want to do that you will need to do that in your project
43
+
using the url provided.
42
44
43
45
44
46
Refreshing feeds
45
47
----------------
46
48
47
-
To conserve resources with large feed lists, the module will adjust how often it polls feeds based on how often they are updated. The fastest it will poll a feed is every hour. The slowest it will poll is every 24 hours.
49
+
To conserve resources with large feed lists, the module will adjust how often it polls feeds
50
+
based on how often they are updated. The fastest it will poll a feed is every hour. The
51
+
slowest it will poll is every 24 hours.
48
52
49
-
Sources that don't get updated are polled progressively more slowly until the 24 hour limit is reached. When a feed changes, its polling frequency increases.
53
+
Sources that don't get updated are polled progressively more slowly until the 24 hour limit is
54
+
reached. When a feed changes, its polling frequency increases.
50
55
51
-
You will need to decided how and when to run the poller. When the poller runs, it checks all feeds that are currently due. The ideal frequency to run it is every 5 - 10 minutes.
56
+
You will need to decided how and when to run the poller. When the poller runs, it checks all
57
+
feeds that are currently due. The ideal frequency to run it is every 5 - 10 minutes.
52
58
53
59
Polling with cron
54
60
-----------------
@@ -83,15 +89,40 @@ There are two ways to track the read/unread state of feeds depending on your nee
83
89
Single User Installations
84
90
^^^^^^^^^^^^^^^^^^^^^^^^^
85
91
86
-
If your usage is just for a single user, then there are helper methods on a ``Source``
92
+
If your usage is just for a single user, then there are helper methods on a Source
87
93
to track your read state.
88
94
89
95
All posts come in unread. You can get the current number of unread posts from
90
96
``Source.unread_count``.
91
97
92
-
To get all the unread posts from a feed in chronological order
98
+
To get a ResultSet of all the unread posts from a feed call ``Source.get_unread_posts``
93
99
100
+
To mark all posts on a fed as read call ``Source.mark_read``
94
101
102
+
To get all of the posts in a feed regardless of read status, a page at a time call
103
+
``Source.get_paginated_posts`` which returns a tuple of (Posts, Paginator)
104
+
105
+
Multi-User Installations
106
+
^^^^^^^^^^^^^^^^^^^^^^^^
107
+
To allow multiple users to follow the same feed with individual read/unread status,
108
+
create a new ``Subscription`` for that Source and User.
109
+
110
+
Subscription has the same helper methods for retrieving posts and marking read as
111
+
Source.
112
+
113
+
You can also arrange feeds into a folder-like hierarchy using Subscriptions.
114
+
Every Subscription has an optional ``parent``. Subscriptions with a ``None`` parent
115
+
are considered at the root level. By convention, Subscriptions that are acting as parent
116
+
folders should have a ``None`` ``source``
117
+
118
+
Subscriptions have a ``name`` field which by convention should be a display name if it is
119
+
a folder or the name of the Source it is tracking. However this can be set to any
120
+
value if you want to give a personally-meaningful name to a feed who's name is cryptic.
121
+
122
+
There are two helper methods in the ``utils`` module to help manage subscriptions as folders.
123
+
``get_subscription_list_for_user`` will return all Subscriptions for a User where the
124
+
parent is None. ``get_unread_subscription_list_for_user`` will do the same but only returns
125
+
Subscriptions that are unread or that have unread children if they are a folder.
Copy file name to clipboardExpand all lines: readme.rst
+37-6Lines changed: 37 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,19 +36,25 @@ A feed is represented by a ``Source`` object which has (among other things) a ``
36
36
37
37
To start reading a feed, simply create a new ``Source`` with the desired ``feed_url``
38
38
39
-
``Sources`` have ``Posts`` a which contain the content.
39
+
``Source`` objects have ``Post`` children which contain the content.
40
40
41
-
``Posts`` may have ``Enclosures`` s which is what podcasts use to send their audio. The app does not download enclosures, if you want to do that you will need to it in your project using the url provided.
41
+
A ``Post`` may have ``Enclosure`` (or more) which is what podcasts use to send their audio.
42
+
The app does not download enclosures, if you want to do that you will need to do that in your project
43
+
using the url provided.
42
44
43
45
44
46
Refreshing feeds
45
47
----------------
46
48
47
-
To conserve resources with large feed lists, the module will adjust how often it polls feeds based on how often they are updated. The fastest it will poll a feed is every hour. The slowest it will poll is every 24 hours.
49
+
To conserve resources with large feed lists, the module will adjust how often it polls feeds
50
+
based on how often they are updated. The fastest it will poll a feed is every hour. The
51
+
slowest it will poll is every 24 hours.
48
52
49
-
Sources that don't get updated are polled progressively more slowly until the 24 hour limit is reached. When a feed changes, its polling frequency increases.
53
+
Sources that don't get updated are polled progressively more slowly until the 24 hour limit is
54
+
reached. When a feed changes, its polling frequency increases.
50
55
51
-
You will need to decided how and when to run the poller. When the poller runs, it checks all feeds that are currently due. The ideal frequency to run it is every 5 - 10 minutes.
56
+
You will need to decided how and when to run the poller. When the poller runs, it checks all
57
+
feeds that are currently due. The ideal frequency to run it is every 5 - 10 minutes.
52
58
53
59
Polling with cron
54
60
-----------------
@@ -83,17 +89,40 @@ There are two ways to track the read/unread state of feeds depending on your nee
83
89
Single User Installations
84
90
^^^^^^^^^^^^^^^^^^^^^^^^^
85
91
86
-
If your usage is just for a single user, then there are helper methods on a ``Source``
92
+
If your usage is just for a single user, then there are helper methods on a Source
87
93
to track your read state.
88
94
89
95
All posts come in unread. You can get the current number of unread posts from
90
96
``Source.unread_count``.
91
97
98
+
To get a ResultSet of all the unread posts from a feed call ``Source.get_unread_posts``
92
99
100
+
To mark all posts on a fed as read call ``Source.mark_read``
93
101
102
+
To get all of the posts in a feed regardless of read status, a page at a time call
103
+
``Source.get_paginated_posts`` which returns a tuple of (Posts, Paginator)
94
104
105
+
Multi-User Installations
106
+
^^^^^^^^^^^^^^^^^^^^^^^^
107
+
To allow multiple users to follow the same feed with individual read/unread status,
108
+
create a new ``Subscription`` for that Source and User.
95
109
110
+
Subscription has the same helper methods for retrieving posts and marking read as
111
+
Source.
96
112
113
+
You can also arrange feeds into a folder-like hierarchy using Subscriptions.
114
+
Every Subscription has an optional ``parent``. Subscriptions with a ``None`` parent
115
+
are considered at the root level. By convention, Subscriptions that are acting as parent
116
+
folders should have a ``None`` ``source``
117
+
118
+
Subscriptions have a ``name`` field which by convention should be a display name if it is
119
+
a folder or the name of the Source it is tracking. However this can be set to any
120
+
value if you want to give a personally-meaningful name to a feed who's name is cryptic.
121
+
122
+
There are two helper methods in the ``utils`` module to help manage subscriptions as folders.
123
+
``get_subscription_list_for_user`` will return all Subscriptions for a User where the
124
+
parent is None. ``get_unread_subscription_list_for_user`` will do the same but only returns
125
+
Subscriptions that are unread or that have unread children if they are a folder.
97
126
98
127
Dealing with Cloudflare
99
128
-----------------------
@@ -105,3 +134,5 @@ It's a huge pain and affects lots of self-hosted RSS readers. Seriously, Google
105
134
``django-feed-reader`` will do it's utmost to get these feeds anyway through the judicious use of public proxy servers, but is haphazard and you cannot rely on the scheduling of such feeds.
106
135
107
136
Feeds blocked by Cloudflare will have the ``is_cloudflare`` flag set on their ``Source`` and will update on a best-efforts basis.
137
+
138
+
For more details see the `full documentation <https//django-feed-reader.readthedocs.io>`_.
0 commit comments