<commit_before>Tutorial: DLKit Learning Service Basics
=======================================

This tutorial is under development. It currently focuses on aspects of the ``Learning`` service. At the
time of this writing, MIT's Office of Digital Learning is supporting a production learning objective management
service called the MIT Core Concept Catalog (MC3_). DLKit includes an underlying implementation that uses MC3 for 
persistence.  As a result, this tutorial uses examples primarily from this particular service, which deals with 
managing learning objectives, learning paths and relationships between learning objectives and educational 
assets, assessments, etc, since there is data available for testing.

.. _MC3: http://mc3.mit.edu/

All of the other DLKit Interface Specifications build on most of the 
same patterns outlined in this tutorial, beginning with loading managers.

The Runtime Manager and Proxy Authentication
--------------------------------------------

Service managers are instantiated through a Runtime Manger, which are designed to work with certain runtime environments,
like Django or edX/XBlock runtimes.  To get access to these runtime environments please contact <EMAIL>.  Install the
runtime environment you want to use and make sure that your Django project's settings.py includes ``dlkit_django`` or 
``dlkit_xblock`` as appropriate.

Now you can get the ``RuntimeManager`` root instance for your runtime environment. Note that there is only one, and 
it gets instantiated at environment launch time, it is thread-safe and used by all consumer application sessions::

    from dlkit_django import runtime

This ``runtime`` object is your gateway to access  all the underlying service managers and their respective service sessions and functionality

The django runtime knows about Django's own services for users.  You will have access to an HTTPRequest object that includes an user authentication (the
request variable in the examples below).  This needs to be encapsulated in a Proxy object::

    from dlkit_django import proxy_session
    condition = proxy_session.get_proxy_condition()
    condition.set_http_request(request)
    proxy = proxy_session.get_proxy(condition)

Or, if you are standing up dlkit in edX, get an XBlockUser() object from the xblock runtime. 
That object is assumed to be stored the 'xblock_user' variable below::

    from dlkit_xblock import proxy_session
    condition = proxy_session.get_proxy_condition()
    condition.set_xblock_user(xblock_user)
    proxy = proxy_session.get_proxy(condition)

Now you have a Proxy object that holds the user data and eventually other stuff, like locale information, etc, 
that can be used to instantiate new service Managers, which you can also insert into your HttpRequest.session::

    from dlkit_django import runtime
    request.session.lm = runtime.get_service_manager('LEARNING', proxy)

For the duration of the session you can use this for all the other things.
that you normally do.

There is a lot more you can do with the ``RuntimeManager``, but getting service managers will be the most common task.  One of the other
important tasks of this manager, is configuration the underlying service stack based on the ``configs.py`` file and associated helpers.  We
will cover this later.

Loading the Learning Manager
----------------------------

All consumer applications wishing to use the DLKit Learning service should start by instantiating 
a ``LearningManager`` (don't worry about the proxy for now)::
 
    lm = runtime.get_service_manager('LEARNING')
    
Everything you need to do within the learning service can now be
accessed through this manager. An OSID service ``Manager`` is used like a factory, providing all
the other objects necessary for using the service. You should never try to instantiate any 
other OSID object directly, even if you know where its class definition resides.

The simplest thing you can do with a manager is to inspect its ``display_name`` and ``description`` 
methods. Note that DLKit always returns user-readable strings  as ``DisplayText``
objects. The actual text is available via the ``get_text()`` method. 
Other ``DisplayText`` methods return the ``LanguageType``, ``ScriptType`` and
``FormatType`` of the text to be displayed::
    <commit_msg>updated RUNTIME and PROXY_MANAGER<commit_after>Tutorial: DLKit Learning Service Basics
=======================================

This tutorial is under development. It currently focuses on aspects of the ``Learning`` service. At the
time of this writing, MIT's Office of Digital Learning is supporting a production learning objective management
service called the MIT Core Concept Catalog (MC3_). DLKit includes an underlying implementation that uses MC3 for 
persistence.  As a result, this tutorial uses examples primarily from this particular service, which deals with 
managing learning objectives, learning paths and relationships between learning objectives and educational 
assets, assessments, etc, since there is data available for testing.

.. _MC3: http://mc3.mit.edu/

All of the other DLKit Interface Specifications build on most of the 
same patterns outlined in this tutorial, beginning with loading managers. Make sure that the dlkit
package is in your python path or install the library.

The Runtime Manager and Proxy Authentication
--------------------------------------------

Service managers are instantiated through a Runtime Manger, which are designed to work with certain runtime environments,
like Django or edX/XBlock runtimes.  To get access to these runtime environments please contact <EMAIL>.  Install the
runtime environment you want to use and make sure that your Django project's settings.py includes ``dlkit_django`` or 
``dlkit_xblock`` as appropriate.

Now you can get the ``RuntimeManager`` root instance for your runtime environment. Note that there is only one, and 
it gets instantiated at environment launch time, it is thread-safe and used by all consumer application sessions::

    from dlkit_django import runtime

This ``runtime`` object is your gateway to access  all the underlying service managers and their respective service sessions and functionality

The django runtime knows about Django's own services for users.  You will have access to an HTTPRequest object that includes an user authentication (the
request variable in the examples below).  This needs to be encapsulated in a Proxy object::

    from dlkit_django import PROXY_SESSION
    condition = PROXY_SESSION.get_proxy_condition()
    condition.set_http_request(request)
    proxy = PROXY_SESSION.get_proxy(condition)

Or, if you are standing up dlkit in edX, get an XBlockUser() object from the xblock runtime. 
That object is assumed to be stored the 'xblock_user' variable below::

    from dlkit_xblock import PROXY_SESSION
    condition = PROXY_SESSION.get_proxy_condition()
    condition.set_xblock_user(xblock_user)
    proxy = PROXY_SESSION.get_proxy(condition)

Now you have a Proxy object that holds the user data and eventually other stuff, like locale information, etc, 
that can be used to instantiate new service Managers, which you can also insert into your HttpRequest.session::

    from dlkit_django import RUNTIME
    request.session.lm = RUNTIME.get_service_manager('LEARNING', proxy)

For the duration of the session you can use this for all the other things.
that you normally do.

There is a lot more you can do with the ``RuntimeManager``, but getting service managers will be the most common task.  One of the other
important tasks of this manager, is configuration the underlying service stack based on the ``configs.py`` file and associated helpers.  We
will cover this later.

Loading the Learning Manager
----------------------------

All consumer applications wishing to use the DLKit Learning service should start by instantiating 
a ``LearningManager`` (don't worry about the proxy for now)::
 
    lm = runtime.get_service_manager('LEARNING')
    
Everything you need to do within the learning service can now be
accessed through this manager. An OSID service ``Manager`` is used like a factory, providing all
the other objects necessary for using the service. You should never try to instantiate any 
other OSID object directly, even if you know where its class definition resides.

The simplest thing you can do with a manager is to inspect its ``display_name`` and ``description`` 
methods. Note that DLKit always returns user-readable strings  as ``DisplayText``
objects. The actual text is available via the ``get_text()`` method. 
Other ``DisplayText`` methods return the ``LanguageType``, ``ScriptType`` and
``FormatType`` of the text to be displayed::
    
{'fraction_non_alphanumeric': 0.07165787663379959, 'fraction_numerical': 0.0009172208209126347, 'mean_word_length': 4.418012422360248, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2805890', 'n_tokens_mistral': 2075, 'n_tokens_neox': 2004, 'n_words': 1152}