Package: xblock-openedx
Part of `edX code`__.__ http://code.edx.org/XBlock Courseware Components |build-status| |coverage-status|=============================================================XBlock is a component architecture by edX.org for building courseware.This is a pre-alpha release of the XBlock API, to gather input from potentialusers of the API.  We like what is here, but are open to suggestions forchanges. We will be implementing this shortly in the edX LMS.This repo contains the core code for implementing XBlocks.Background----------EdX courseware is built out of components that are combined hierarchically.These include components like the video player, `LON-CAPA`_ problems, as wellas compound components like learning sequences. We are developing asecond-generation API for these components called XBlocks. Although they're ina prototype stage, we like the API, and want to collaborate with others todevelop them into an industry standard. This is our proposed API andspecification for XBlocks... _LON-CAPA: http://www.lon-capa.org/How does this differ from existing industry standards like `Learning ToolsInteroperability`_ (LTI) and `SCORM`_? On a high level, XBlocks is a Pythonlanguage-level API, and it provides sensible defaults for things like storingdata. XBlocks could be wrapped up in LTI, and one could make an LTI XBlock. Thecore reason to write an XBlock is that it is deployable. You can give us thecode to an XBlock, and we can embed it in our courseware. LTI would require youto give us a virtual machine image which ran it... _Learning Tools Interoperability: http://www.imsglobal.org/toolsinteroperability2.cfm.. _SCORM: http://scorm.com/scorm-explained/Installation------------This code runs on Python 2.7. If you prefer to use Python 3, there is `a forkof XBlock that provides Python 3 support`_, but this fork is not yet supportedby edX.1.  Get a local copy of this repo.2.  (Optional)  Create and activate a virtualenv to work in.3.  Install the requirements and register the XBlock entry points with (you mayneed to sudo this if you don't use virtualenv):$ pip install -r requirements.txt.. _a fork of XBlock that provides Python 3 support: https://github.com/singingwolfboy/XBlock/tree/py3Testing--------To run the test suite:$ nosetestsThis will run:* Unit tests of the XBlock core and runtime.To run the test suite under coverage:$ coverage run -m noseto execute the tests. Then to view the coverage report:$ coverage reportSee the `coverage.py`_ docs for more info and options... _coverage.py: http://nedbatchelder.com/code/coverage/Style Testing-------------We use two tools - ``pylint`` and ``pep8`` - to manage the code quality and styleof all Python files in this repo. Our goal is to maintain zero reported pylintand pep8 violations at all times.To run these tools on a single file:$ pylint path/to/file.py$ pep8 path/to/file.pyTo run these tools on the whole project:$ pylint .$ pep8 .We do not abide by all pylint and pep8 violations. You can check out which violationswe ignore by viewing the contents of `pylintrc`_ and `setup.cfg`_. Before making a pullrequest, you should ensure that your branch does not add any new quality violationsby checking your code with these tools... _pylintrc: https://github.com/edx/XBlock/blob/master/pylintrc.. _setup.cfg: https://github.com/edx/XBlock/blob/master/setup.cfgYou can run these tests automatically before pushing code to github (and runningthe validation in Travis) by activating the `pre-push` scriptcd .git/hooksln -s ../../script/pre-pushcd -Using the XBlock-SDK-------------------The XBlock-SDK exists in a separate repository. The SDK contains useful tools fordeveloping your own XBlocks, such as a template XBlock generator, sample XBlocksthat demonstrate XBlock functionality.You can find it in its own repository: https://github.com/edx/xblock-sdkDocumentation-------------The docs for the XBlock API is on Read The Docs:  https://xblock.readthedocs.org .Reading the code----------------There are distinct layers to this code.  In the docstrings, we've tried to makeclear which layer the code lives in, though sometimes the lines are blurred:1.  **XBlock** The sample XBlock code.  This is the most important, it is thecode that most third parties will be writing, and demonstrates the XBlockinterfaces.2.  **Runtime** The runtime code that we think will be common to all runtimes.This is the behind-the-scenes code edX will write to make XBlocks work.This layer may not be real code here, but we'll need to write real code toperform these functions.Making your own XBlock----------------------Making an XBlock can be as simple as creating a Python class with a fewspecific methods.Instructions for constructing a new XBlock along with examples can be found inthe XBlock SDK: https://github.com/edx/xblock-sdkLicense-------The code in this repository is licensed the Apache 2.0 license unless otherwisenoted.Please see ``LICENSE.txt`` for details.How to Contribute-----------------Contributions are very welcome. The easiest way is to fork this repo, and thenmake a pull request from your fork. The first time you make a pull request, youmay be asked to sign a Contributor Agreement.Please refer to our `contributor guidelines <https://github.com/edx/edx-platform/blob/master/CONTRIBUTING.rst>`_ in the main edx-platform repo forimportant additional information.Reporting Security Issues-------------------------Please do not report security issues in public. Please email security@edx.orgPackaging---------To package a new release, first tag the commit to be released$VERSION=0.5git tag -a -m "XBlock version $VERSION" xblock-$VERSIONthen upload to PyPImake packageAll of the heavy lifting is handled by python-versioneer (https://github.com/warner/python-versioneer)Mailing List and IRC Channel----------------------------You can discuss this code on the `edx-code Google Group`__ or in the``#edx-code`` IRC channel on Freenode.__ https://groups.google.com/group/edx-code.. |build-status| image:: https://travis-ci.org/edx/XBlock.svg?branch=master:target: https://travis-ci.org/edx/XBlock.. |coverage-status| image:: https://coveralls.io/repos/edx/XBlock/badge.svg:target: https://coveralls.io/r/edx/XBlock