scripttoollib-slides.txt

.. include:: <s5defs.txt>
.. |br| raw:: html

   <br />

========================
Names for code fragments
========================
(based on reusability)
----------------------

:Author: kr
:Date: 2013

.. contents:: Table of Contents
  :class: handout


Code categories
===============

- Script
- Tool
- Lib


Category: Script
================

- means written down
- performs a *concrete task*
- is directly *executable*
- has all its parameters *hard coded* |br|
  → take *NO* user given parameters
- is *NOT reusable* by design
- might be incomplete


Are you kidding?
================

I know from *experience*, that

.. class:: incremental

- reuse is possible by *modifying* the script
- modification of scripts is the *most common* reuse of all

`???`


Problem: depending on code modification
=======================================

- code modification is inherently a manual work
- manual work directly translates to time
    - where to modify?
    - what to modify?
    - test... test...

.. class:: incremental

  - would I be happy to take over the task of running someone else's scripts?


Are scripts bad, then?
======================

.. class:: incremental

  Hell, NO!

  .. container::

    They

    - are extremely useful building blocks
    - are the easiest to create compared to other components
    - can be made relocatable and complete
    - can be quite easily "upgraded" to become *tools*


Strict scripts
==============

- *complete* - runnable without user interaction
- *relocatable* - can be run on another computer or in another directory

Relocatable scripts are explicit about their dependencies.

E.g. in python they are accompanied with a *requirements.txt*.


Category: Tool
==============

- directly *executable*
- reusability supported by *parameters*
- *independent* of developer's machine
- *easily installable* with dependencies

.. class:: big incremental

  Is it a script, then?


Tools are not scripts
=====================

The "script" you might think of have

- *hard coded parameters*

  - potentially restricting the code to run only on the developer's machine
  - usable for one set of data
- *no machine readable* description of used libraries, dependencies


Category: Library
=================

- *NOT executable*
- *pure reusable code*
- *invisible* for the user
- *solve hard problems* or provides *convenience*
- eliminates the need for code repetition
  (in other words: minimalizes boilerplate)
- should be *tested* and *bug free*
- must be *known* to be used
- must have a good *documentation*, to be usable
- requires *patience and skill* to build
- thus, good libraries are very *valuable*



### How do different kinds
### of codes work together?

<br />

Every code can use *libraries* and call *tools*, but generally

<br />

- #### a tool makes functionality in a library accessible to end-users
- #### a library provides new functionality to other code



### How can we reuse code?



## Packages


### Python packaging
### is a mess :(

Packages are stored in a variety of formats:

- [binary and source] `eggs` (deprecated)
- [source] tar balls
- zips
- `wheels` (maybe the future?)


### Package repositories

Collect user installable packages.

The main (or public) repository is: https://pypi.python.org/pypi

Our private one is at http://devpi.microdata.ceu.hu


### Using python packages

- virtualenv
- pip
- configuration for our own package index (TBD, `.pip/pip.conf`)


### STATA packages

This looks like describing one packaging solution:

http://www.stata.com/support/ssc-installation/

Other STATA solutions are looking cookbook like by description.
(correct me if they are not!)



### Examples
Script
...
TBD



# THE END