Welcome to the Abilian Core documentation

Abilian - Connected we work

Welcome to Abilian Core’s documentation.

Abilian Core is an enterprise application development platform based on the Flask micro-framework, the SQLAlchemy ORM, good intentions and best practices (for some value of “best”).

The full documentation is available on http://docs.abilian.com/.

It builds on powerful and well documented Python librairies, mainly:

This documentation will assume that a developer already has some knowledge of these librairies.

Contents

About Abilian Core

Abilian Core is an enterprise application development platform based on the Flask micro-framework, the SQLAlchemy ORM, good intentions and best practices (for some value of “best”).

The full documentation is available on http://docs.abilian.com/.

Goals & principles

  • Development must be easy and fun (some some definition of “easy” and “fun”, of course)
  • The less code (and configuration) we write, the better
  • Leverage existing reputable open source libraries and frameworks, such as SQLAlchemy and Flask
  • It must lower errors, bugs, project’s time to deliver. It’s intended to be a rapid application development tool
  • It must promote best practices in software development, specially Test-Driven Development (as advocated by the GOOS book)

Features

Here’s a short list of features that you may find appealing in Abilian:

Infrastructure
  • Plugin framework
  • Asynchronous tasks (using Celery)
  • Security model and service
Domain model and services
  • Domain object model, based on SQLAlchemy
  • Audit
Content management and services
  • Indexing service
  • Document preview and transformation
Social
  • Users, groups and social graph (followers)
  • Activity streams
User Interface and API
  • Forms (based on WTForms)
  • CRUD (Create, Retrieve, Edit/Update, Remove) interface from domain models
  • Labels and descriptions for each field
  • Various web utilities: view decorators, class-based views, Jinja2 filters, etc.
  • A default UI based on Bootstrap 3 and several carefully selected jQuery plugins such as Select2
  • REST and AJAX API helpers
  • i8n: support for multi-language via Babel, with multiple translation dictionaries
Management and admin
  • Initial settings wizard
  • Admin and user settings framework
  • System monitoring (using Sentry)

Current status

Abilian Core is currently alpha (or even pre-alpha) software, in terms of API stability.

It is currently used in several applications that have been developped by Abilian over the last two years:

  • Abilian SBE (Social Business Engine) - an enterprise 2.0 (social collaboration) platform
  • Abilian EMS (Event Management System)
  • Abilian CRM (Customer / Contact / Community Relationship Management System)
  • Abilian Le MOOC - a MOOC prototype
  • Abilian CMS - a Web CMS

In other words, Abilian Core is the foundation for a small, but growing, family of business-critical applications that our customers intend us to support in the coming years.

So while Abilian Core APIs, object model and even architecture, may (and most probably will) change due to various refactorings that are expected as we can’t be expected to ship perfect software on the firt release, we also intend to treat it as a valuable business asset and keep maintaining and improving it in the foreseeable future.

Roadmap & getting involved

We have a roadmap on Pivotal Tracker that we use internally to manage our iterative delivery process.

For features and bug requests (or is it the other way around?), we recommend that you use the GitHub issue tracker.

Licence

Abilian Core is licensed under the LGPL.

Credits

Abilian Core has been created by the development team at Abilian (currently: Stefane and Bertrand), with financial support from our wonderful customers, and R&D fundings from the French Government, the Paris Region and the European Union.

We are also specially grateful to:

  • Armin Ronacher for his work on Flask.
  • Michael Bayer for his work on SQLAlchemy.
  • Everyone who has been involved with and produced open source software for the Flask ecosystem (Kiran Jonnalagadda and the HasGeek team, Max Countryman, Matt Wright, Matt Good, Thomas Johansson, James Crasta, and probably many others).
  • The creators of Django, Pylons, TurboGears, Pyramid and Zope, for even more inspiration.
  • The whole Python community.

Installing Abilian Core

If you are a Python web developer (which is the primary target for this project), you probably already know about:

  • Python 2.7
  • Virtualenv
  • Pip

So, after you have created and activated a virtualenv for the project, just run:

pip install -r requirements.txt

To use some features of the library, namely document and images transformation, you will need to install the additional native packages, using our operating system’s package management tools (dpkg, yum, brew…):

  • A few image manipulation libraries (libpng, libjpeg)

  • The poppler-utils, unoconv, LibreOffice, ImageMagick utilities

  • lesscss:

    For Debian/Ubuntu the package is named node-less. If your distribution’s package is too old, you may install node-js >= 0.10 and npm. Lesscss can then be installed with:

    $ sudo npm install -g less
    npm http GET https://registry.npmjs.org/less
    npm http 200 https://registry.npmjs.org/less
    ...
    $ which lessc
    /usr/bin/lessc
    

Testing

Abilian Core come with a full unit and integration testing suite. You can run it with make test (once your virtualenv has been activated).

Alternatively, you can use tox to run the full test suite in an isolated environment.

Contributing to Abilian Core

Project on GitHub

The project is hosted on GitHub at: https://github.com/abilian/abilian-core.

Participation in the development of Abilian is welcome and encouraged, through the various mechanisms provided by GitHub:

Build Status

We give a great deal of care to the quality of our software, and try to use all the tools that are at our disposal to make it rock-solid.

This includes:

  • Having an exhaustive test suite.
  • Using continuous integration (CI) servers to run the test suite on every commit.
  • Running tests.
  • Using our products daily.

You can check the build status:

You can also check the coverage reports:

Releasing

We’re now using setuptools_scm to manage version numbers.

It comes with some conventions on its own when it comes to releasing.

Here’s what you should do to make a new release on PyPI:

  1. Check that the CHANGES.rst file is correct.
  2. Commit.
  3. Tag (ex: git tag 0.3.0), using numbers that are consistent with semantic versionning.
  4. Run python setup.py sdist upload.

Coding standard

We recommend using the PEP8 and Google coding standard, with the following exceptions:

  • Indentation should be 2 chars, not 4.

Additional rules

TODO

Notes

Line length

We stick to the “no lines longer than 80 characters” rule despite the fact that we’re living in a post VT-220 world.

Here’s some rationale by user “badsector” on Reddit:

I used to use a 120 character limit or ignore E501 on my pep8 checker (python), but eventually went back to the default 80 character limit. I realized it did more for me than let me fit 4 files side by side on a laptop screen:

  • It discouraged me from writing long sprawling if statements and method chains.
  • With less space, I thought more assigning about clear and concise names for things.
  • I would break out deeply nested ifs and other control statements into separate functions. This is probably the biggest win since smaller code pieces are easier to unit test due to lowered cyclomatic complexity.

API

Package abilian

Module abilian.app
Module abilian.i18n

Package abilian.core

Module abilian.core.entities
Module abilian.core.extensions
Module abilian.core.logging
Module abilian.core.signals
Module abilian.core.sqlalchemy
Module abilian.core.models
Module abilian.core.util

Package abilian.services

Module abilian.services.base
Module abilian.services.activity
Module abilian.services.audit
Module abilian.services.conversion
Module abilian.services.image
Module abilian.services.indexing
Module abilian.services.security

Package abilian.web

Module abilian.web.attachments
Module abilian.web.comments
Module abilian.web.filters
Module abilian.web.action
Module abilian.web.nav
Module abilian.web.forms
Module abilian.web.views
Module abilian.web.frontend
Module abilian.web.tags
Module abilian.web.util

Package abilian.testing

Changelog for Abilian Core

v0.11.19 (2021-04-07)

  • Cut a new release to fix the docs.

v0.11.18 (2021-03-16)

  • Prevent upgrading to SQLAlchemy 1.4

v0.11.10 (2020-08-04)

  • Fix tests.
  • Cleanup API.
  • Use sentry sdk instead of raven.
  • Cleanup.

v0.11.7 (2020-07-30)

  • Format.
  • Docstrings.
  • Fix/silent lint errors.
  • Cosmit py3k.
  • Format.
  • Marketing.
  • Modernize code.
  • Prettify front-end.
  • Use proper booleans.
  • Ci: add nox tests.
  • Ci: fix noxfile.
  • Ci: refact tox config.
  • Ci: use bionic for travis.

v0.11.6 (2019-12-29)

Fix
  • New flake8 warnings.
Other
  • Ci: Github actions.
  • Ci: travis / py38.
  • Refactor: f-strings.

v0.11.4 (2019-09-12)

  • Typing + format.
  • Py3k.
  • Travis for 3.8 (not working)

v0.11.3 (2019-08-07)

Fix
  • Search wasn’t really configurable.
  • Fix bug on debug toolbar for signals.
Other
  • Remove “pyre-fixme” comments.
  • Small refactor (f-strings).
  • Typing issues fixed.
  • Fix for readthedocs.
  • Fix doc (sphinx) issues.
  • Fix tests.
  • Type hints.
  • Typing fixes.
  • Fix settings.
  • Cleanup imports.
  • Py3k-ize settings. May break things.
  • Fix typing (pyre) issues.
  • Format.
  • Annotate w/ type warnings.
  • Refactor: use f-strings.
  • Py3k: using pyupgrade.

v0.11.6 (2019-12-29)

Fix
  • New flake8 warnings.
Other
  • Ci: Github actions.
  • Ci: travis / py38.
  • Refactor: f-strings.

v0.11.5 (2019-10-07)

  • Deps

v0.11.4 (2019-09-12)

  • Typing + format.
  • Py3k.
  • Travis for 3.8 (not working)

v0.11.3 (2019-08-07)

Fix
  • Search wasn’t really configurable.
Other
  • Annotate w/ type warnings.
  • Cleanup imports.
  • Fix bug on debug toolbar for signals.
  • Fix doc (sphinx) issues.
  • Fix for readthedocs.
  • Fix settings.
  • Fix tests.
  • Fix typing (pyre) issues.
  • Format.
  • Py3k-ize settings. May break things.
  • Py3k: using pyupgrade.
  • Remove “pyre-fixme” comments.
  • Small refactor (f-strings).
  • Type hints.
  • Typing issues fixed.

v0.11.2 (2019-06-28)

  • Add flake8-mypy.
  • Add type annotations.
  • Better variable naming.
  • Class BlobQuery is not needed.
  • Cleanup imports.
  • Couple of typing fixes.
  • Fix incomplete refactoring.
  • Format + typing.
  • Make more robust.
  • Py3k.
  • Refactor caching.
  • Refactor conversion service.
  • Refactor: extract variable.
  • Set up CI with Azure Pipelines.
  • Skip test when soffice not available.
  • Typing.

v0.11.1 (2019-05-02)

  • A couple of typing fixes.
  • Dont run flake8-mypy for now.

0.11.0 (2019-04-15)

  • Drop Python 2 support.
  • Rewrite code to be Python 3 only.
  • Various fixes.

0.10.34 (2019-01-17)

  • Simplify indexing control DSL: __indexation_params__ -> __index_to__.

0.10.34 (2019-01-17)

  • Simplify indexing control DSL: __indexation_params__ -> __index_to__.

0.10.32 (2019-01-02)

  • Switched dependency management to poetry
  • Py3k migration and fixes.

0.10.29 (2018-12-26)

  • Cleanup, small fixes related to updated dependencies.

0.10.29 (2018-12-26)

  • Cleanup, small fixes related to updated dependencies.

0.10.20 (2018-07-19)

  • Clean up audit objects by removing null values on init

0.10.15 (2018-07-05)

  • Unpin pillow, small cleanups.

0.10.14 (2018-06-11)

  • pin wtforms because 2.2 breaks our tests

0.10.12 (2018-04-27)

  • Fix for Flask 1.0

0.10.11 (2018-04-15)

  • Fix install under pip 10

0.10.8 (2018-04-04)

  • Refactor pytest fixtures. API has changed.

0.10.3 (2018-02-22)

  • Cleanup JS

0.10.2 (2018-02-21)

  • Refactor tests (use pytest fixtures)
  • Refactor Application class

0.10.2 (2018-02-15)

  • Fix Py3k compatibility.

0.10.0 (2018-02-12)

Breaking changes:

  • Removed deprecated plugin loader
  • Renamed is_support_attachments to supports_attachments

Other:

  • Refactoring tests to use pytest’s function-based tests instead of unittest’s class-based tests.

0.9.30 (2018-01-11)

  • Don’t depend on psycopg2, so you can use your favorite driver (ex: pg8000).

0.9.19-0.9.29

  • Cleanup
  • Bug fixes
  • Python 3 compatibility
  • Dependencies updates

0.9.18 (2017-10-06)

  • Relax dependency constraint on Bleach to allow upgrade of other deps.

0.9.17 (2017-10-02)

  • Cleanup
  • Fix some warnings.

0.9.16 (2017-09-08)

  • JS cleanup and linting
  • Deps updates

0.9.15 (2017-09-04)

  • Revert some buggy JS “clean up”.
  • Deps updates

0.9.12 (2017-08-28)

  • Code clean up.

0.9.11 (2017-08-03)

  • Workaround bug in Babel related to Python 3.

0.9.10 (2017-08-02)

  • Cleanup and prepare for Python 3.

0.9.9 (2017-08-01)

  • Cleanup and prepare for Python 3.
  • Use headless libreoffce for conversion instead of unoconv.

0.9.3 (2017-07-03)

  • Add “impersonate” admin panel.

0.9.3 (2017-06-30)

  • Fix bug on form_valid

0.7.24 (2017-01-10)

  • Downgrade Ravenjs :(

0.7.21 (2017-01-09)

  • Ravenjs update
  • Update deps

0.7.10 (2016-08-30)

  • Fix issue with raven-js logging

0.7.9 (2016-08-29)

  • More robust reindex command.
  • Pytest > 3.0 compat

0.7.8 (2016-08-04)

  • Use bcrypt library instead of py-bcrypt.
  • Work on Py3k compatibility (not done yet)
  • Update dependencies.

0.7.7 (2016-07-13)

  • Work on Py3k compatibility (not done yet)
  • Remove unneeded dependencies.
  • Update dependencies.
  • Harder linting.

0.7.0 (2016-05-31)

  • Made compatible with Flask 0.11, SQLAlchemy 1.0 and a few other recent releases.
  • General cleanup.

0.6.5 (2016-05-10)

Workaround some regression by not generating less source map.

0.6.2 (2016-05-09)

  • Fix import error.

0.6.1 (2016-05-09)

  • Allow SQLAlchemy 0.9.x for now
  • Allow application/x-pdf mime type.

0.6.0 (2016-04-29)

  • Upgrade SQLAlchemy to 1.0+.
  • Dump config in sysinfo admin panel

Cleanup:

  • Upgrade deps
  • Reformat code using Google style rule

0.5.3-0.5.6 (2016-03-17)

Features:

  • dynamic row widget options to add controls at the bottom (23 hours ago)<yvon>

Fixes:

  • fix datatable optionalcriterion filter (2 days ago)<yvon>
  • fix jquery datable jqmigrate warning (2 days ago)<yvon>
  • fix search criterion outerjoin (6 days ago)<yvon>
  • textsearch criterion mysterious onclause fix (9 days ago)<yvon>

Cleanup:

  • Upgrade deps
  • Reformat code using Google style rule

0.5.2 (2016-02-16)

  • Fix IPv6 / GeoIP issue
  • Improve debug toolbar
  • Improve dashboard
  • Celery: expire task before next run scheduled

0.5.1 (2016-01-29)

  • add security debug panel: shows permissions and roles assignments
  • faster query_with_permission()
  • Fix: user administration could remove non-assignable roles
  • Subforms (Form used in FormFields / ListFormFields / etc) can filter their fields according to permission passed to top Form.

0.5.0 (2015-11-20)

  • Editable comments
  • Upgrade SQLAlchemy to 0.9
  • Admin: add Tag panels

0.4.5 (2015-10-15)

Improvements and updates
  • Breaking: minor schemas changes. Migrations needed for existing applications
  • tags in ‘default’ namespace are indexed in document’s text for full text search on tag label
  • age filter has a new option to show full date when date is not today
  • run command: add –ssl option
  • admin: manage groups membership from user page
  • updated requirements to ensure sane minimum versions
  • Role based access control makes more permissions checks againts roles and less simple role check
Fixes
  • fixes for celery workers
  • fix: check user has role on object with global role
  • fix: check user has roles through group membership

0.4.4 (2015-08-07)

Design / UI
  • Navbar is now non-fluid.
Updates
  • Upgrade Jinja to 2.8 and Babel to 2.0
Fixes
  • Fixed image cropping.

0.4.3 (2015-07-29)

Another release because there was a version number issue with the previous one.

0.4.2 (2015-07-29)

Bugfixes / cleanup
  • Replace Scribe by CKEditor for better IE compatibility.
  • Smaller bug fixes and code cleanups

0.4.1 (2015-07-21)

Bugfixes / cleanup

0.4.0 (2015-07-15)

Features
  • Object level permissions
  • Add “meta” properties to entities
  • Attached files to entities
  • More flexible search filters
  • Avatars
  • Tag engine (alpha)
Fixes / cleanup
  • JS: Upate ravenjs, requirejs, bootbox, jquery, scribe

0.3.6 (2015-05-27)

Fixes
  • security service: fix exception on has_role()

0.3.5 (2015-05-27)

Features
  • default user avatar is now a circle with their last name initial (#12)
  • add PRIVATE_SITE, app, blueprint and endpoint access controller registration
  • Better handling of CSRF failures
  • add dynamic row widget js
  • js: add datatable advanced search
Fixes
  • CSS (Bootstrap) fixes
  • Permissions fixes
Updates
  • Updated Bootstrap to 3.3.4
  • Updated flask-login to 0.2.11
  • Updated Sentry JS code to 1.1.18

0.3.4 (2015-04-14)

  • updated Select2 to 3.5.2
  • enhanced fields and widgets
  • set default SQLALCHEMY_POOL_RECYCLE to 30 minutes
  • Users admin panel: fix roles not set; fix all assignable roles not listed; fix cannot set password during user creation.

0.3.3 (2015-03-31)

Features
  • Use ravenjs to monitor JS errors with Sentry
  • Vocabularies

0.3.2 (2014-12-23)

  • Minor bugfixes

0.3.1 (2014-12-23)

  • Minor bugfixes

0.3.0 (2014-12-23)

Features
  • Added a virus scanner.
  • Changed the WYSIWYG editor to Scribe.
  • Vocabularies
API changes
  • Deprecated the @templated decorator (will be removed in 0.4.0).
Building, tests
  • Build: Use pbr to simplify setup.py.
  • Dependencies: moved deps to ./requirements.txt + cleanup / update.
  • Testing: Tox and Travis config updates.
  • Testing: Run tests under Vagrant.
  • QA: Fixed many pyflakes warnings.

0.2.0 (2014-08-07)

  • Too long to list.

0.1.4 (2014-03-27)

  • refactored abilian.core.entities, abilian.core.subjects. New module abilian.core.models containing modules: base, subjects, owned.
  • Fixed or cleaned up dependencies.
  • Fixed setupwizard.
  • added config value: BABEL_ACCEPT_LANGUAGES, to limit supported languages and change order during negociation
  • Switched CSS to LESS.
  • Updated to Bootstrap 3.1.1

0.1.3 (2014-02-03)

  • Update some dependencies
  • Added login/logout via JSON api
  • Added ‘createuser’ command

0.1.2 (2014-01-11)

  • added jinja extension to collect JS snippets during page generation and put them at end of document (“deferred”)
  • added basic javascript to prevent double submission
  • Added Flask-Migrate

0.1.1 (2013-12-26)

  • Redesigned indexing:
    • single whoosh index for all objects
    • search results page do not need anymore to fetch actual object from database
    • index security information, used for filtering search results
    • Added “reindex” shell command

0.1 (2013-12-13)

  • Initial release.

Credits

Design, programming

Abilian development team: 2012-2013.

Indices and tables