rename project_root to site_aspen

[pjz]

Per @techtonik :

Rename project_root to site_aspen (stolen that convention from SCons - it is also "placed on sys.path during startup). The problem with project_root that it is not a root of a project (like Gratipay) - it is a site-specific dir for Aspen configuration. The project may consist of many things, and web site might only be a minor. Also it is a good practice to keep root of the project checkout tidy for newcomers. Having sane defaults also help to avoid learning lengthy command lines. By default aspen could look for site_aspen in current dir (like SCons) and try to load www as default too, so that you could just invoke 'aspen' for development, without environment, foreman, Makefiles and all that complication. In addition, project_root is not searchable, but site_aspen is.

[pjz]

project_root is a site-specific dir for Aspen configuration and code. It gets added to sys.path, so site-specific modules and code go there as well. So maybe site_code ? or code_root (to match www_root) ? py_root ?

[techtonik]

What is the problem that needs to be solved? That simplate in www can not import project modules if they are not in site_aspen? If that's the case, we can use just src default or generic importable sys.path entry. If we take analogy with Django, the www are our urls+views+templates, and src is models.

[pjz]

site_aspen solves two problems:

1. Simplates cannot import project modules unless they're in site_aspen or on sys.path.
2. It's a place to put configure-aspen.py (documented here )which can be used to configure the Website object at startup.

src is a reasonable alternate name for function 1, but I'm not sure it's reasonable given function 2.

[chadwhitacre]

It's a place to put configure-aspen.py

Haven't we deprecated configure-aspen.py?

[techtonik]

configure-aspen.py looks like a settings.py in Django terminology. Django allows to switch between different settings, like dev, prod, etc. Does configure-aspen.py support that?

In Google App Engine app configuration is handled by root level app.yaml script. We may use similar static map that select various configuration details and serves as an entrypoint to the app structure.

[chadwhitacre]

My understanding is that we are removing the magic configure-aspen.py in #381. Instead, one configures an aspen.Website from yer own Python:

from aspen import Website
from my_app import wireup()

website = Website()

wireup(website)

See gratipay/gratipay.com#3151 for a fuller example.

[techtonik]

Right, but being able to just run aspen and do development is a feature.

Without some convention, how will aspen find config to find app files? If there is no convention and pure Python, then we will need some executable script app.py in the root that can be run standalone, but is also a wsgi application. Something like manage.py, but working as a devserver by default.

[chadwhitacre]

Right, but being able to just run aspen and do development is a feature.

For simple cases, the answer is python -m aspen.

If there is no convention and pure Python, then we will need some executable script app.py in the root that can be run standalone, but is also a wsgi application. Something like manage.py, but working as a devserver by default.

Yup. Write your own! :-)

from aspen.website import Website

website = Website([])

if __name__ == '__main__':
    from wsgiref.simple_server import make_server
    make_server('', 8000, website).serve_forever()

[chadwhitacre]

or code_root (to match www_root)

How about config_root and www_root?

[techtonik]

I only don't understand how a python -m aspen is supposed to work. At the very least it needs to guess the location of wsgi file.

[chadwhitacre]

I only don't understand how a python -m aspen is supposed to work.

Here's the code behind python -m aspen. It has the effect of launching aspen with the current working directory as www_root, and no {project,config}_root. See the docstring for more.

[techtonik]

I see. So, we need some convention how aspen command can become more useful by discovering site settings automatically (instead of empty config_root). It may just scan all *.py and *.wsgi files for modules that import aspen.

[chadwhitacre]

So, we need some convention how aspen command can become more useful by discovering site settings automatically (instead of empty config_root).

There is no aspen command. Are you suggesting we (re)introduce one?

[techtonik]

There is no aspen command. Are you suggesting we (re)introduce one?

Well, running aspen could be easier that trying to figure out the correct combination of WSGI scripts, servers and different paths. I really had to learn a lot to get Gratipay working - I already knew about WSGI, Makefiles, server processes, but it took few days to learn about Procfiles, Heroku, foreman and honcho, which are embedded into make run. Oh, yea - also about default.env, and not there is configure-aspen.py It will really help to be able to just run aspen, get some info about what is where and start hacking.

[chadwhitacre]

1. Gratipay's configuration system is out of scope for Aspen.
2. Having an aspen executable wouldn't impact Gratipay's configuration system, unless we folded honcho's features into the aspen executable. We're not going to do that, because that would bloat Aspen.

[pjz]

Let's stay on topic: should we rename project_root to site_aspen? or some other name?

[chadwhitacre]

By default aspen could look for site_aspen in current dir (like SCons) and try to load www as default too, so that you could just invoke 'aspen' for development, without environment, foreman, Makefiles and all that complication.

We're not going to go back to magic directory names. The answer here is an environment variable:

$ cd www/
$ ASPEN_PROJECT_ROOT=path/to/config python -m aspen

In addition, project_root is not searchable, but site_aspen is.

@techtonik Do you mean that I can't grep inside project_root? Or that I can't find project_root? Or ... ?

Let's stay on topic: should we rename project_root to site_aspen? or some other name?

+1 configuration_root

[pjz]

configuration_root is too long. How about config_root ? or code_root ?

[chadwhitacre]

🚲 🏠

[chadwhitacre]

The problem with project_root that it is not a root of a project (like Gratipay) - it is a site-specific dir for Aspen configuration.

project_root precisely is the root of the project on Gratipay.

The project may consist of many things, and web site might only be a minor.

So what? Then the website is just a subproject, and website.project_root still makes sense.

Also it is a good practice to keep root of the project checkout tidy for newcomers.

I don't see that this relates.

Having sane defaults also help to avoid learning lengthy command lines.

I don't know how to make sense of this in the present context.

[pjz]

Okay, you've convinced me that I should instead just be 👎 on this. So, that.

[techtonik]

We're not going to go back to magic directory names.

project_root is the magic name.

@techtonik Do you mean that I can't grep inside project_root? Or that I can't find project_root? Or ... ?

WTF project_root? Let's ask Google. http://lmgtfy.com/?q=project_root Have I already told a story about The Curse of Knowledge? Knowing that you need to go to aspen site to find out about Gratipay's project_root is just about it.

The configuration_root is no different. You need to be more specific. For external people it is aspen specific configuration for Gratipay application, not vice versa.

project_root precisely is the root of the project on Gratipay.

I see that it is where Aspen looks for its files, and that's why there is a lot of garbage in Gratipay's root. =)

Having sane defaults also help to avoid learning lengthy command lines.

I don't know how to make sense of this in the present context.

Let me remind you that the current way to run inside.gratipay.com is ./$(env_bin)/honcho -e defaults.env,local.env run ./env/bin/aspen --network_address :8536 --www_root=./www/ --project_root=./. There is no chance for me to remember that line. It could be just aspen. Like it is for AppEngine wher for codereview.appspot,com the command to run is dev_appserver.py .

[chadwhitacre]

project_root is the magic name.

Then I'm not sure what you mean by "magic name". What I mean by magic name is that aspen would automatically discover the directory based on its special name. This is what you were proposing for site_aspen, and it's what we used to do for __ and also for .aspen.

Have I already told a story about The Curse of Knowledge?

Not that I recall.

Knowing that you need to go to aspen site to find out about Gratipay's project_root is just about it.

That's a function of Aspen's tiny market share, a problem that renaming to site_aspen doesn't solve.

I see that it is where Aspen looks for its files, and that's why there is a lot of garbage in Gratipay's root. =)

Here is the Gratipay root:

-rw-r--r--   1 whit537  staff    100 May 12 23:33 .babel_extract
-rw-r--r--   1 whit537  staff  13488 Jun 17 16:41 .coverage
-rw-r--r--   1 whit537  staff    414 May 12 23:33 .editorconfig
drwxr-xr-x  16 whit537  staff    544 Jun 18 00:43 .git/
-rw-r--r--   1 whit537  staff     89 May 12 23:33 .gitattributes
-rw-r--r--   1 whit537  staff    270 May 21 07:11 .gitignore
-rw-r--r--   1 whit537  staff     87 May 12 23:33 .jshintrc
-rw-r--r--   1 whit537  staff    146 May 12 23:33 .slugignore
-rw-r--r--   1 whit537  staff    154 Mar 30 11:19 .transifexrc
-rw-r--r--   1 whit537  staff    902 May 12 23:33 .travis.yml
drwxr-xr-x   3 whit537  staff    102 May 12 23:33 .tx/
-rw-r--r--   1 whit537  staff    545 May 12 23:33 410.spt
-rw-r--r--   1 whit537  staff    531 May 12 23:33 CONTRIBUTING.md
-rw-r--r--   1 whit537  staff   8021 May 12 23:33 COPYING
-rw-r--r--   1 whit537  staff   1862 May 12 23:33 Dockerfile
-rw-r--r--   1 whit537  staff   3992 May 12 23:33 Gruntfile.js
-rw-r--r--   1 whit537  staff   2992 Jun 17 19:56 Makefile
-rw-r--r--   1 whit537  staff     65 May 12 23:33 Procfile
-rw-r--r--   1 whit537  staff  21829 Jun 11 18:36 README.md
-rw-r--r--   1 whit537  staff   2938 May 12 23:33 Vagrantfile
-rwxr-xr-x   1 whit537  staff   1432 May 12 23:33 backup.sh*
drwxr-xr-x   8 whit537  staff    272 Jun 17 19:56 bin/
drwxr-xr-x   3 whit537  staff    102 Jun 11 08:12 data/
-rw-r--r--   1 whit537  staff   2594 May 12 23:33 defaults.env
drwxr-xr-x   7 whit537  staff    238 Jun 17 19:56 docs/
drwxr-xr-x   9 whit537  staff    306 Jun 11 16:31 emails/
-rw-r--r--   1 whit537  staff   1060 May 12 23:33 error.spt
drwxr-xr-x  16 whit537  staff    544 Jun  1 20:37 gratipay/
-rwxr-xr-x   1 whit537  staff   3051 May 12 23:33 gratipay.py*
drwxr-xr-x   4 whit537  staff    136 Jun 17 10:23 i18n/
drwxr-xr-x   4 whit537  staff    136 May 12 23:33 img-src/
drwxr-xr-x   5 whit537  staff    170 May 29 02:22 js/
-rw-r--r--   1 whit537  staff    499 Jun 17 17:50 local.env
-rwxr-xr-x   1 whit537  staff    111 May 12 23:33 masspay.sh*
drwxr-xr-x  11 whit537  staff    374 Jun 17 16:41 node_modules/
-rw-r--r--   1 whit537  staff  59687 Jun 11 12:42 npm-shrinkwrap.json
-rw-r--r--   1 whit537  staff    418 Jun 11 12:42 package.json
-rw-r--r--   1 whit537  staff   1921 May 18 11:56 payday.py
-rwxr-xr-x   1 whit537  staff   2202 May 12 23:33 payday.sh*
-rw-r--r--   1 whit537  staff   7192 Jun 17 16:41 phantomjsdriver.log
-rwxr-xr-x   1 whit537  staff   1275 May 12 23:33 recreate-schema.sh*
-rwxr-xr-x   1 whit537  staff   2767 May 12 23:33 release.sh*
-rw-r--r--   1 whit537  staff    611 May 12 23:33 requirements.txt
-rw-r--r--   1 whit537  staff    200 May 12 23:33 requirements_tests.txt
-rw-r--r--   1 whit537  staff     13 May 12 23:33 runtime.txt
drwxr-xr-x   6 whit537  staff    204 May 12 23:33 scripts/
drwxr-xr-x  11 whit537  staff    374 May 29 02:22 scss/
-rw-r--r--   1 whit537  staff    397 May 12 23:33 setup.py
drwxr-xr-x   9 whit537  staff    306 Jun 11 16:56 sql/
drwxr-xr-x   3 whit537  staff    102 May 12 23:33 tasks/
drwxr-xr-x  33 whit537  staff   1122 Jun 17 10:23 templates/
drwxr-xr-x   5 whit537  staff    170 May 12 23:33 tests/
drwxr-xr-x  57 whit537  staff   1938 May 12 23:33 vendor/
drwxr-xr-x  24 whit537  staff    816 May 29 02:22 www/

Here are the files that aspen looks for in that directory in virtue of it's being the website.project_root:

-rw-r--r--   1 whit537  staff    545 May 12 23:33 410.spt
-rw-r--r--   1 whit537  staff   1060 May 12 23:33 error.spt

In other words, Aspen is only responsible for a couple error simplates (and we already have a ticket to make their location configurable: #141). Yes, the Gratipay root could be cleaned up. No, Aspen is not to blame for the mess.

Let me remind you that the current way to run inside.gratipay.com is ./$(env_bin)/honcho -e defaults.env,local.env run ./env/bin/aspen --network_address :8536 --www_root=./www/ --project_root=./.

No it's not, it's make run. Or (with a simple shell alias), r. What's more, the version of Gratipay we're using on IG has an aspen executable. It's in the line you pasted.

[chadwhitacre]

The configuration_root is no different. You need to be more specific. For external people it is aspen specific configuration for Gratipay application, not vice versa.

@techtonik Now we might be getting somewhere. If I hear you right, you're saying that if you look at gratipay/main.py and you see a website, and you have a vague sense that it comes from Aspen, but what is it? You inspect it in the debugger and see that it has a project_root on it. You think "website means Gratipay" because that's the website you're working on, but website.project_root is something other than Gratipay. Yes?

I still don't buy it, sorry. :-)

Honestly I think we just need to bring Aspen as a library up to snuff with Postgres.py, etc., in terms of documentation and API design. Maybe project_root survives that process, maybe it doesn't. But we're not going to make progress while our attention is zoomed in on such a tiny detail. We need to approach the task with a much wider perspective. Therefore, I'm closing this ticket as a 🚲 🏠.

[techtonik]

Then I'm not sure what you mean by "magic name".

"magic name" is the name of variable with a very low change of correct guess about its true meaning.

What I mean by magic name is that aspen would automatically discover the directory based on its special name.

This is called convention and discovery and it can be fixed by #437 in which you can google aspen_site convention. But you have no chance to find project_root convention unless you already know aspen.

[techtonik]

Ah. Whatever. You won't understand me. It is a waste of time.

[techtonik]

Just a hint. I am using windows without GCC, Makefiles and all that stuff that make Linux users happy. Right now I also debug all this on remote container, where is no debugger or IDE.

[techtonik]

I also don't see why not to use Flask + simplates. What is the role of Aspen? How does it compare to Flask and Djangi?

[chadwhitacre]

I'm sorry Aspen sucks right now. :-(

[techtonik]

It suxx only because it is not properly explained.. Looks like NIH with no clear rationale.