What is project_root?

[techtonik]

#438 gone wrong, and I think it is a miscommunication. The conflicting point for is is that project_root is explained as "junk drawer" for importable modules, "catchall for files that don’t belong in your actual URL hierarchy" @ http://aspen.io/project_root/

The actual usage of it in Gratipay is to point to a root of the root of the project to find all other modules. Kind of crippled sys.path for running without virtualenv, so that import gratipay may succeed. IMHO for that a import_paths name better reflects the use name. More than that - it is a set of paths hardcoded for every application.

Now how to set it. The so-called project_root is also used for storing configuration files. This is double purpose and that's why it is so hard to decouple. Clearly, to find out import_paths they need to be defined somewhere, so aspen application (or wsgi entrypoint) needs to get the idea of where the settings are located.

The discovery mechanism for settings location should be the primary focus for unwinding the complexity issue with project_path. Currently, there is no discovery that I know of. The project_root is used to locate some configure-aspen.py (which needs to contain import_paths) and project_root is specified on command line or hardcoded into WSGI scripts.

The correct way is to specify only one file - config or setting file in command line, provide sane default if there is no such file, and inside of that file, specify relative paths to all other dirs and files, such as mime.types.

Does that sound good?

[chadwhitacre]

The actual usage of it in Gratipay is to point to a root of the root of the project to find all other modules. Kind of crippled sys.path for running without virtualenv, so that import gratipay may succeed.

That's how it's used on inside.gratipay.com. On gratipay.com we actually install gratipay as a proper Python module (see setup.py and the env target in the Makefile; the Heroku python buildpack installs it for us in production).

The pattern here is: just throw it in project_root to get started, and upgrade to a full Python package when the time is right.

The discovery mechanism for settings location should be the primary focus for unwinding the complexity issue with project_path. Currently, there is no discovery that I know of. The project_root is used to locate some configure-aspen.py[.]

Don't forget: configure-aspen.py is going away, because Aspen is a library. It's not a framework or a server. It's a library.

[chadwhitacre]

The first hit on Google for project_root is to an old Django ticket (probably Django is where I got the name in the first place?), which includes this comment:

The "project" metaphor is only temporary and shouldn't be fortified in yet another setting.

And then this alternative:

[...] BASE_DIR, which is essentially the same as PROJECT_DIR, except the name is semantically correct.

I'm open to adopting that line of thinking: "project" is a metaphor, and we should prefer non-metaphorical names. Maybe for our case we have something like:

• website.www_dir (was www_root)
• website.base_dir (was project_root)
• website.error_dir (see add an error_root knob #141)

[chadwhitacre]

Maybe spt_dir instead of www_dir?

[chadwhitacre]

(In any case, site_aspen means nothing to me, having never worked much with SCons. :)

[techtonik]

This lacks details. I can not say if names are good or bad, because as you see, for the the usage of project_root is very confusing. The practical question - where to put an extension module for Aspen like the one iGP uses for navigation?

www_root is good, because it is the root of you site structure, not just dir.
base_dir I associate with Apache rewrite rules, and it is confusing. What will be the role of this dir?
error_dir - the same (role in unclear). From #141 - "Right now Aspen looks for error simplates in the project_root.". Why not in www_root?

[pjz]

project_root is for holding configure-aspen.py. That's all. Incidentally, by default it gets added to sys.path, so you can put whatever you want there.

Also, I'm against _dir because they're already directories. No need to encode type in the name. _root is handy because it goes with the tree metaphor that all filesystems already embrace.

aspen_root ? code_root ? 🚲 🏠 , as @whit537 said.