1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
.. _codebase-chapter:
========================
Codebase Documentation
========================
.. contents:: Sections
:local:
This chapter covers the libraries that GNU MediaGoblin uses as well as
various recipes for getting things done.
.. Note::
This chapter is in flux. Clearly there are things here that aren't
documented. If there's something you have questions about, please
ask!
See `the join page on the website <http://mediagoblin.org/join/>`_
for where we hang out.
For more information on how to get started hacking on GNU MediaGoblin,
see `the wiki <http://wiki.mediagoblin.org/>`_.
Software Stack
==============
* Project infrastructure
* `Python <http://python.org/>`_: the language we're using to write
this
* `Nose <http://somethingaboutorange.com/mrl/projects/nose/>`_:
for unit tests
* `virtualenv <http://www.virtualenv.org/>`_: for setting up an
isolated environment to keep mediagoblin and related packages
(potentially not required if MediaGoblin is packaged for your
distro)
* Data storage
* `MongoDB <http://www.mongodb.org/>`_: the document database backend
for storage
* Web application
* `Paste Deploy <http://pythonpaste.org/deploy/>`_ and
`Paste Script <http://pythonpaste.org/script/>`_: we'll use this for
configuring and launching the application
* `WebOb <http://pythonpaste.org/webob/>`_: nice abstraction layer
from HTTP requests, responses and WSGI bits
* `Routes <http://routes.groovie.org/>`_: for URL routing
* `Beaker <http://beaker.groovie.org/>`_: for handling sessions and
caching
* `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
* `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
validation, and abstraction from HTML forms
* `Celery <http://celeryproject.org/>`_: for task queuing (resizing
images, encoding video, ...)
* `MongoKit <http://namlook.github.com/mongokit/>`_: the lightweight
ORM for MongoDB we're using which will make it easier to define
structures and all that (will be swapped out soon...)
* `SQLAlchemy <http://sqlalchemy.org/>`_: SQL ORM and database
interaction library for Python. We'll be moving to this in the
upcoming move to SQL.
* `Babel <http://babel.edgewall.org>`_: Used to extract and compile
translations.
* `Markdown (for python) <http://pypi.python.org/pypi/Markdown>`_:
implementation of `Markdown <http://daringfireball.net/projects/markdown/>`_
text-to-html tool to make it easy for people to write richtext
comments, descriptions, and etc.
* `lxml <http://lxml.de/>`_: nice xml and html processing for
python.
* Media processing libraries
* `Python Imaging Library <http://www.pythonware.com/products/pil/>`_:
used to resize and otherwise convert images for display.
* `GStreamer <http://gstreamer.freedesktop.org/>`_: (Optional, for
video hosting sites only) Used to transcode video, and in the
future, probably audio too.
* `chardet <http://pypi.python.org/pypi/chardet>`_: (Optional, for
ascii art hosting sites only) Used to make ascii art thumbnails.
* Front end
* `JQuery <http://jquery.com/>`_: for groovy JavaScript things
What's where
============
After you've run checked out mediagoblin and followed the virtualenv
instantiation instructions, you're faced with the following directory
tree::
mediagoblin/
|- mediagoblin/ # source code
| |- tests/
| |- templates/
| |- auth/
| \- submit/
|- docs/ # documentation
|- devtools/ # some scripts for developer convenience
|
| # the below directories are installed into your virtualenv checkout
|
|- bin/ # scripts
|- develop-eggs/
|- lib/ # python libraries installed into your virtualenv
|- include/
|- mediagoblin.egg-info/
|- parts/
|- user_dev/ # sessions, etc
As you can see, all the code for GNU MediaGoblin is in the
``mediagoblin`` directory.
Here are some interesting files and what they do:
:routing.py: maps url paths to views
:views.py: views handle http requests
:models.py: holds the mongodb schemas---these are the data structures
we're working with
You'll notice that there are several sub-directories: tests,
templates, auth, submit, ...
``tests`` holds the unit test code.
``templates`` holds all the templates for the output.
``auth`` and ``submit`` are modules that enacpsulate authentication
and media item submission. If you look in these directories, you'll
see they have their own ``routing.py``, ``view.py``, and
``models.py`` in addition to some other code.
|
