buttercup: a flower for k0s.org
===============================

buttercup is a ``flower`` that is used to bloom a website like
`k0s.org <http://k0s.org>`_.  There are several `python <http://python.org>`_
components to a buttercup website:

 * `decoupage <http://k0s.org/portfolio/software.html#decoupage>`_: for static files and indices
   - `montage <http://k0s.org/portfolio/software.html#montage>`_for image galleries
   - contenttransformer for static file presentation
 * `bitsyblog <http://k0s.org/portfolio/software.html#bitsblog>`_ for blogging
 * a set of mercurial repositories
 * software demos:
   - anagram
   - wordstream
 * and so forth


why is buttercup so messy?
--------------------------

Easy.  Its the backport of a highly specific website to a flower.  The
buttercup flower is in fact a study in botany, useful in the study of
species, but probably less interesting as a practical deployment for
widescale use.


does buttercup work yet?
------------------------

Depends on what you want to do.  Right now, what `buttercup` does is
mostly best gleaned from the source code.  I hope to change this with time.


what is a flower?
-----------------

Every website has, in essence, an intent, a purpose the website serves
and tools and method with which to enact such purpose.  While the
intent itself belongs to the domain of natural language, the tools
(read: web applications) and how they are deployed (including
e.g. request dispatching) should be catalogued in a manner actionable
to machine.

A flower is a deployment pattern of a website.

The deployment pattern contains information about what tools (usually,
python packages) are required, how they are set up for an instance of
the pattern, and how they interact with each other; but it does not
contain content (including site-static content) save in abstract.

For example, imagine you are making a very simple website where you
want static files and directories served from the path info segment
``/``, a blog served at ``/blog``, and the ability to upload files to
whatever directory ``/`` corresponds to on the web server's
filesystem. (Let's also make it real simple and completely ignore auth
which you should definitely *NOT* do if you were to deploy this flower.)
If you were me, you'd probably use
`decoupage <http://k0s.org/hg/decoupage/>`_
 for the file server,
`bitsyblog <http://k0s.org/hg/bitsyblog/>`_
for the blog software,
and `uploader <http://k0s.org/hg/uploader/>`_
for the file upload widget.
This would be a *flower*.  It has a clear intent -- a blog and file
server -- and a set of tools that manifests that intent.
You could have variations on this, such as mounting the blog at ``/``
and files at ``/files``, but since the deployment intentions are the
same (the tools interact with each other the same way, from a machine
point of view).  It would be of merit to write this example flower,
but such shall be reserved for an exercise to the reader (which may
very well be me).


I'm a programmer.  Can you give me a briefer explanation?
---------------------------------------------------------

Assuming you know object-oriented programming, a flower would be the
*class* of the website, and the website would be the instance.


what should a flower look like?
-------------------------------

As said, buttercup is currently messy.  It was written as a marriage
between a very minimalistic need of saving some time on very specific
problems and the abstract idea of flowers which I didn't have time to
delve in.  Voila! Software is born.  In addition, even had I the best
intentions and time available to them, technologies such as more
recent pip changes were not available at the time of crafting.

Also, I'm lazy and/or don't have time to work on it.

In essence, ``buttercup`` has (or should have):

- a list of software requirements (that should be installed in
``--develop`` mode in a ``virtualenv``)
- a method of "fitting the pipes" with
  `wsgintegrate <http://k0s.org/hg/wsgintegrate/>`_
- (and there's also something about ensuring system packages are
   installed and what not; see e.g
   http://k0s.org/hg/buttercup/file/c008855cf3a9/buttercup/PACKAGES.txt
   though I believe it is yet unused)

If I were to incorporate these as concepts into ``buttercup``, I would
make the flower have:

- a ``pip``
  `requirements file <http://www.pip-installer.org/en/latest/requirements.html>`_

- a skeleton of a ``wsgintegrate`` ``.ini`` file and methods to
  interpolate this skeleton to the instance

- *and*, very importantly but very forgettably, tools to port
   production changes to the ``wsgintegrate`` configuration back to
   the flower.

- (in addition formalize the system packages (obviously per platform)
  needed and how to check for them install them etc.  Not sure if
  there is stuff out there for this; outside of the fact that several
  platforms have to be supported, its a pain.  Vagrant and puppet seem
  close...ish. Silverlining?)

Obviously, this sort of make-up works for ``buttercup``.  It would not
work so well if, say, you were using apache + mod_wsgi vs
e.g. wsgintegrate and a standalone WSGI server.  While the latter (and
other) software stacks can certainly be part of flowers, I care less
about them for my personal development needs/wants.  You could imagine
a buttercup variant, built roughly the same but with e.g. apache.
While the intents are close, that is a different flower ... at least
until an abstraction layer is written to obviate that difference (the
clause itself being very illustrative as to what a flower *is*).


why is this all coded into buttercup?  why not have one or more base packages?
------------------------------------------------------------------------------

So far all I've needed to care about was k0s.org for purposes of
flowers.  Being not one to repeat code and being very much one to put
things in the right place, if there is an event to abstract the logic,
abstract I will.


so what's the advantage of flowers, anyway?  is this just for deployment?
-------------------------------------------------------------------------

While I've presented flowers as a deployment pattern for a website,
that is mostly for expedience and because such language is easily
understood.  While of course this is directly usable for deployment, I
am more interested in classification.  Its kinda like design patterns
or whatever other sorts of patterns:  having a copy of the catalog
does not guarantee an understanding of taxonomy.

There are technical advantages at looking at websites and their
deployments as evolving pattern.  There is the generic: the flower;
and there is the newly deployed site.  But both change and evolve.
You can make a new flower from the old.  You can use a flower as part
of a flower.  They become building blocks.

I want to make something crazy called *flowerbed* which combines some
generic flower software (to be written) with wsgintegrate and a web
interface to manipulating directed graphs (also to be written).  With
this and a little elbow grease and unicorn dust, you could write a
tool to allow you to make a flower (and also the website, if desired)
just by drawing a graph with a preselected set of tools and pipes.
But, as usual, postponed until needed.


it seems like it'd be cool if ``buttercup``
and other flowers were insantiable TTW.
-------------------------------------------

It does, doesn't it?  You should write that!  Or maybe I will someday.