Switch to functional/stateless architecture

[kalekundert]

Currently, BYOC is tightly coupled to the app object. This has some downsides:

• It's not possible to use BYOC without an app object, e.g. in simple scripts where a dictionary would otherwise suffice.
• The app objects end up keeping a bunch of intermediate state for their entire lifetimes, even though (in principle) that state can be dropped once the "final" values are calculated.

I believe that moving to a functional/stateless architecture would address both of these points, and make the code more extensible in general. By "functional/stateless architecture", I mean roughly that there would be a load(params, configs) function that would return a dict/object with all the specified information.

However, it's not clear how all of the useful features of BYOC would be reimplemented in such a system. The purpose of this thread is to enumerate and discuss such features.

[kalekundert]

DocoptConfig: Using parameters when loading configs

• Fundamentally, I'll need to call load() twice, with different config arguments. Some ways to do this:
  • Provide the necessary information to all configs: Config.iter_layers(params, configs).
  • Given DocoptConfig a method like calc_usage_text(params, configs) that would need to be called manually.
  • Make the user responsible for passing DocoptConfig a filled-in object.
  • This appeals to me, because the job of a config is to load information form a source. It should be given all the information it needs to do that.
  • But it's not totally clear how I'd make this a nice class-based API:
    • The necessary info would have to be provided by the __config__ factory.
    • The factories are specific to the class interface, so I don't need to worry about messing up the clean functional interface here.
    • Regardless, the factories would need access to the configs/params.
    • Currently they are passed just the app itself.
    • I could pass them the configs and params as well, or I could store everything in the class. I don't want to store things, so that points to the former.
    • The factories would have to integrate config values (e.g. to show argument defaults) and miscellaneous object attributes (e.g. to show config paths). It wouldn't be hard to write a wrapper class for that, though.
  • A key insight is that the object used to format the usage text is not the ultimate app object. This enables two convenient properties: apps can only be configured once, and apps can't be half-configured.

[kalekundert]

UpstreamConfig: Reusing configs from other apps

• Configs are layer factories.
• These layers need to be stored somewhere, in order for other apps to reuse them:
  • If I store them in the apps themselves, then they'll be there for the lifetime of the object.
  • Otherwise, I have to force the user to manage them:
  • With stepwise, this comes up when adding reagents to reactions.
  • Reagents can be added at any time, so I'd need to either keep the configs around or recalculate them each time.
  • Currently, UpstreamConfig takes an app, and finds it's partner within that app itself. Maybe instead I could just give it the config to use.

---

• Maybe UpstreamConfig isn't a good fit for BYOC: I could move it to stepwise-sample along with a protocol for saving the configs and accessing them later.
  • In some sense, this config is very tied up with the network of reactions/reagents that stepwise-sample is meant to help facilitate.
  • This way, the various SWMB entities would still store their configs for their entire lifetimes, but that wouldn't be something dictated by BYOC.
• Configs shouldn't have state: their role it just to generate layers.
• In order to implement the above, though, I'll need a ConfigCache object.
  • This will basically be an add-only dict with config keys and List[layer] values.
  • This object should be part of BYOC, and an optional argument/return value for load(). It will be necessary to efficiently implement the DocoptConfig factory. Plus it's a useful tool for things like this.
  • stepwise-sample would associate one of these caches with each Sample object. UpstreamConfig would be able to read and populate this cache.

[kalekundert]

Part: Deriving multiple parameters from a single config value

• This should actually be pretty easy.
• Pseudocode:
  • Within the load() function:
  • Identify these groups.
  • Load the corresponding value.
  • Assign the parts to each parameter.
  • This requires the load() function to treat these getters specially. How can I keep all of the logic contained within the getter?
  • Shared state dictionary.
  • Give each group a unique key.
  • Assign value to state dict with that key, then look it up.

[kalekundert]

Never overwrite manually specified values

• This is more of a danger with the load() function, since the natural thing to do would just be to overwrite everything.
• I'd also need to take care to distinguish between values set by the user, and values set by a previous call to load.
  • This might not be possible. I could have metadata indicating where each value came from, but that can get out of date depending on how to user assigns attributes.

[kalekundert]

Config initialization

• Currently, all the config classes are initialized with the app object.
• This isn't ideal:
  • All the configs really need is to load values from somewhere. They don't need the app to do this, they just need some of the information that might be contained in the app.
• Move all this to the factories:
  • Configs have no knowledge of the apps
  • Config factories do, though, and use that knowledge to correctly instantiate configs.
• Three ways to specify values for configs:
  • Factory kwargs
  • App attributes
  • Class variables
• I can probably write some code to simplify this:
  • Define "setting" descriptors for config classes.
  • Factories find all settings and set as appropriate.
  • Can instruct factory to look for different attribute, to prevent name clashes.
• I'd still like for the config classes themselves to be valid factories.
  • Currently this works trivially, because the constructor is a factory.
  • But now I want the constructor to be purely in terms of "settings" kwargs, while the factory will accept an app/configs/params object.
  • Maybe I can look for a class method with a certain name, then fall back on the given callable.

[kalekundert]

Class-based interface

• The functional interface will require the configs to be completely configured and ready to go.
• The class-based interface will try to be more streamlined:
  • The __config__ factories will take responsibility for actually configuring the configs.
  • All parameters are automatically calculated and installed when any one parameter is accessed.
  • Apps can't be half-initialized:
    • Either every parameter has a value, or none do.
    • I'm not totally sure if this will solve issues like #47. It will be necessary to set sample.parent before calling load(), but that doesn't seem to onerous. Configs are immutable, so it doesn't matter what order the configs are used in.
  • Apps can't be reloaded:
    • There's no perfect way to distinguish between a value set/modified by the user vs one set by load(), so once a value has been set, I need to respect it.
    • I could add a load(force=True) flag to override this.
  • One parameter could depend on another. So when doing this automatic loading, I need a way to detect this:
    • Have descriptors raise a unique exception.
    • If catch that exception while trying to get an parameter value, skip it and add it to a list of parameters to try later.
    • This should specifically be a dict, so that I can detect cycles rather than getting infinite loops.

[kalekundert]

Method getter

• This intrinsically needs to know about the app.
• First thought:
  • load() should accept an app argument, which is the object it will fill in.
  • This object will somehow be made available to the getters.
  • Not sure if I still want to have "bound getters".
  • This would preclude using dictionaries as the "primary currency" of load().
  • The alternative would be to make the dictionary available to the getter, and to have the getter wrap the dict in SimpleNamespace before calling the method. But then it's not really a method, since it doesn't have access to all methods of the real class.
  • I don't see any alternative to just not using dicts.
• I think I might be able to get rid of bound getters altogether, by passing the app to getter.iter_values().

[kalekundert]

Having thought about this for a while, I don't think I can transition stepwise to a stateless architecture:

• Reagents can be added to samples at any time, so there's no way to know when a sample is "complete", i.e. ready to load. This means that I'd have to force the user to manually load each reagent and sample, and I just don't think that that API is acceptable.
• Loading parameters at the time that they're accessed is a natural way around this problem. By the time you're accessing an attribute, it's reasonable (and intuitive to API users) to assume that all the prerequisite reagents have been added to the sample by then. Importantly, though, accessing one attribute doesn't imply that any others are ready, which is why it's not really tractable to have an API that automatically loads everything once the first attribute is accessed.

However, the stateless architecture makes much more sense for a general-purpose library: it's simpler, more efficient, and more extensible. Without a stateless architecture, I couldn't see myself recommending this library to other people, nor could I see myself using it for anything other than stepwise. So I think a stateless architecture is essential.

Putting this all together, I think I need to support both architectures. More specifically, I need to implement a stateful architecture using the stateless architecture. This would actually be a good way to demonstrate the extensibility of the stateless architecture.

Some implementation details I have in mind:

• Apps would have some configuration option that specifies how parameters should behave when they need a value. The options would be (i) raise an exception explaining that load() needs to be called, (ii) attempt to load that parameter, or (iii) attempt to load all parameters.
• Define a "context" object that would store all the state necessary to load parameters. This object would hold the app itself, the (complete) list of configs to use, config layers, resolved getters for each parameter, miscellaneous data structures to communicate between parameters (e.g. for Part), etc.
  • If the app already has a context object, use that and try to load the parameter.
  • In stateless mode, the context object would be created within the load() function, stored in the app (so that all the parameters could find it), and deleted once everything has been loaded.
  • In stateful mode, the context object would be created by the first parameter that gets accessed, then permanently stored in the app and possibly updated each time a new parameter is accessed. It'd probably make sense to provide a cleanup() function that could get rid of it.
  • Currently I have the concept of bound/unbound getters/configs. Bound objects hold a pointer to the app itself, and can get access to all the caches stored in the app via that pointer. I'd get rid of this concept, and just have getters/configs receive the context object as an argument.
• I'd want to have pretty smart cache objects. For example, say I want to cache the layers from a config. I'd pass the config the context object, which would contain the app being loaded. If the config doesn't actually use any information in the app, though, I could cache the resulting layers in such a way that they could be used by other apps.
  • Case study: the stepwise configuration file. Currently I have a stepwise config that looks in all the places where a stepwise config file could be found and returns a layer for each. This is app-independent. But the config also allows the user to specify a "root key", in which case the config becomes app-dependent. Maybe I want to allow configs to depend on other configs. In this example, there would be an app-independent stepwise config that just loads every file it can find, and another app-dependent stepwise config that loads the independent one then yields copies of all those layers with a different root key. Fundamentally this is just letting the config make use of the cache that's already there, but this seems like a good way to do it.
• Regarding the docopt issue, where some parameters can be loaded multiple times:
  • Some options:
  • Store every value produced by a getter, and associate it with a version number. Every time a parameter value is needed, use the cached values unless they're out of date. This would require a very detailed cache, though, and I'd need to call the picker every time a value is accessed. I think this is too much.
  • Clear the parameter-value cache each time a new config is loaded. This is pretty simple, but wasteful because it doesn't make an effort to avoid recalculating things that aren't affected by the new config.
  • Allow getters to raise NotReadyYet. This would indicate that the parameter could change value in the future (e.g. once more configs are loaded), but for now this getter should just be skipped.
    • It's nice that this isn't inherently tied to Key getters, even though I can't think of any reason why a non-Key getter would need to raise this exception.
    • I'd like some way for this exception to indicate what it's waiting on, otherwise load() could get stuck in an infinite loop (by trying to keep going until all "pending" parameters have values). Maybe I could have the context keep an internal version number that increments every time something about the context changes. If I get NotReadyYet twice for the same parameter with the same context version number, that's an infinite loop.
  • I like the NotReadyYet idea. It seems pretty elegant.

Pseudocode for load():

• Decide which configs to actually use.
• Create context object and store it in the app.
• For each config:
  • Load the config and store its layer in the cache. Note that this might recursively load parameters.
• While there are parameters without values:
  • If the parameter already has a value, mark it as complete.
  • Tell the parameter to load itself. Note that this might recursively load other parameters as well.
  • If all getters were "ready", mark it as complete. Otherwise check for infinite loops.
• Remove context object from app.

Pseudocode for stateful parameter access:

• If app doesn't have a context object:
  • This must be the first parameter being accessed.
  • Decide which configs to use:
  • Include all explicit=False configs
  • If user previously called enable(app, configs), also include those configs.
  • Create context object and store it in the app.
  • For each config:
  • Load the config and store its layers in the cache. Note that this might recursively load parameters.
• Get value for this parameter:
  • If have a valid cached value, return it immediately.
  • Otherwise, invoke getters until the picker is satisfied, then cache and return the resulting value.