Feedjack 15.02.17

Python module (Django app)

This feedjack fork is a regular package for Python 2.7 (not 3.X).

Best way to install it (from PyPI) would be to use pip:

% pip install Feedjack

If you don’t have it, use:

% easy_install pip
% pip install Feedjack

Alternatively (see also pip2014.com and install guide):

% curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python
% pip install Feedjack

Current-git version can be installed like this:

% pip install 'git+https://github.com/mk-fg/feedjack.git#egg=Feedjack'

All of these will automatically fetch and install ‘feedjack’ Django app to a configured python site-path, along with all the required dependencies.

Another way of installing from a git chechout would be running python setup.py install in the dir.

Note that to install stuff in system-wide PATH and site-packages, elevated privileges are often required. Use “install –user”, ~/.pydistutils.cfg or virtualenv to do unprivileged installs into custom paths.

Django project

If you are not familiar with Django framework and how Django apps are deployed, please see this short tutorial, which contains all the steps necessary to initialize “django project” directory, also explaining what’s in there:

https://docs.djangoproject.com/en/stable/intro/tutorial01/#creating-a-project

Django project - at it’s minimum - is just a few configuration files, specifying which database to use, and which “apps” should handle which URLs.

Feedjack can only be deployed as an “app” in such project, so it either has to be created, or app can be enabled in any existing one.

Enabling app in a Django project

• First of all, ‘feedjack’ app must be enabled in settings.py under INSTALLED_APPS.

  Running ./manage.py syncdb (“syncdb” command) from the command line should then populate database (whichever is configured in the same file) with feedjack-specific schema.

• If Django 1.7+ is used (highly recommended), or South app is available (with older Django versions), make sure to add it to INSTALLED_APPS as well, so it’d be able to apply future database schema updates effortlessly.

  ./manage.py migrate feedjack should be run in addition to syncdb in that case, both initially, and (ideally) on every “feedjack” app update (in case there were any db schema changes).

• Feedjack “static files” directory should be setup to be reachable under configured STATIC_URL (under “STATIC_URL/feedjack/”, to be precise).

  This can be done automatically by using django.contrib.staticfiles app, that will copy/link static files with ./manage.py collectstatic command.

  It can also be done manually. For instance, if your STATIC_URL resolves to “/var/www/htdocs”, and Feedjack was installed to “/usr/lib/python2.7/site-packages/feedjack”, symlinking dir from there should probably do the trick:

  % ln -s /usr/lib/python2.7/site-packages/feedjack/static/feedjack /var/www/htdocs/

• Be sure to enable/add/uncomment “django.contrib.admin” app (Django admin interface) as well, since it’s the most convenient and supported way to configure and control feedjack.

  “syncdb” operation (same as after enabling feedjack itself) might be necessary after that.

  Other ways to configure and control feedjack app after installation are:

  • Command-line tools.

    These are accessible via django-admin.py (or “./manage.py” wrapper) - see --help output for reference on all the supported commands there.

    Some (e.g. “feedjack_update”) can also be installed as python console_scripts entry points.

  • Manipulate models from the python code or ./manage.py shell directly, which might be desirable for some kind of migration or automated configuration.

• Add an entry for feedjack.urls in your Django “urls.py” file, so it’d look like this (with admin interface also enabled on “/admin/”):

  urlpatterns = patterns( '',
      (r'^admin/', include('django.contrib.admin.urls')),
      (r'', include('feedjack.urls')) )

  (of course, less trivial Django configurations should probably have way more entries there)

After all that, it might be worth checking out “/admin” section (if django.contrib.admin app was enabled) to create a feedjack site, otherwise sample default site will be created upon first request.

See also “Configuration” section below.

Requirements

• Python 2.7 (not 3.X)

• feedparser 4.1+

• Django 1.7+

• (optional) lxml - used for html mangling in some themes (fern, plain) processing of more free-form timestamps on feeds, if feedparser can’t handle these for whatever reason.

• (optional, only for updating from older Feedjack/Django versions) South

Updating from older versions

The only non-backwards-compatible changes should be in the database schema, thus requiring migration, but it’s much easier (automatic even) than it sounds.

Feedjack didn’t have any automatic db migration features in the past, then used South module (in this fork), and now uses stock Django database migration features (which only work with Django-1.7+).

• To upgrade older installations where there were no migrations in use at all, install and enable South app, backup “feedjack/migrations” (which now contains Django-native migration info), then rename “feedjack/migrations.south” dir to “feedjack/migrations”.

  There is no automated way to determine schema version in current database, so use South’s ./manage.py migrate --list command to list migrations, find the one that matches current db state and run e.g. ./manage.py migrate feedjack 0013 --fake to make South aware of it.

  In case of pre-fork Feedjack versions (0.9.16 and below), this would be very first (0001) schema version.

• To upgrade from South to Django-1.7+ native migrations, temporarily restore “migrations.south” dir to “migrations”, as outlined above, run ./manage.py migrate to make sure all South migrations were applied, then restore Django’s “migrations” directory, replace “south” with “django.db.migrations” in INSTALLED_APPS and run ./manage.py migrate again to apply all these.

  See also Upgrading from South section in Django docs on migrations.