ViX. rSrSSKJr SSKJrJrJrJr SSKJr Sr \ SSSS S S S S / r Sr SSjr Sr SSjrg)aFace Middleware =============== When using Face's Command framework, Face takes over handling dispatch of commands and subcommands. A particular command line string is routed to the configured function, in much the same way that popular web frameworks route requests based on path. In more advanced programs, this basic control flow can be enhanced by adding middleware. Middlewares comprise a stack of functions, each which calls the next, until finally calling the appropriate command-handling function. Middlewares are added to the command, with the outermost middleware being added first. Remember: first added, first called. Middlewares are a great way to handle general setup and logic which is common across many subcommands, such as verbosity, logging, and formatting. Middlewares can also be used to perform additional argument validation, and terminate programs early. The interface of middlewares retains the same injection ability of Command handler functions. Flags and builtins are automatically provided. In addition to having its arguments checked against those available injectables, a middleware _must_ take a ``next_`` parameter as its first argument. Then, much like a decorator, that ``next_`` function must be invoked to continue to program execution:: import time from face import face_middleware, echo @face_middleware def timing_middleware(next_): start_time = time.time() ret = next_() echo('command executed in:', time.time() - start_time, 'seconds') return ret As always, code speaks volumes. It's worth noting that ``next_()`` is a normal function. If you return without calling it, your command's handler function will not be called, nor will any other downstream middleware. Another corollary is that this makes it easy to use ``try``/``except`` to build error handling. While already practical, there are two significant ways it can be enhanced. The first would be to provide downstream handlers access to the ``start_time`` value. The second would be to make the echo functionality optional. Providing values from middleware -------------------------------- As mentioned above, the first version of our timing middleware works, but what if one or more of our handler functions needs to perform a calculation based on ``start_time``? Common code is easily folded away by middleware, and we can do so here by making the start_time available as an injectable:: import time from face import face_middleware, echo @face_middleware(provides=['start_time']) def timing_middleware(next_): start_time = time.time() ret = next_(start_time=start_time) echo('command executed in:', time.time() - start_time, 'seconds') return ret ``start_time`` is added to the list of provides in the middleware decoration, and ``next_()`` is simply invoked with a ``start_time`` keyword argument. Any command handler function that takes a ``start_time`` keyword argument will automatically pick up the value. That's all well and fine, but what if we don't always want to know the duration of the command? Whose responsibility is it to expose that optional behavior? Lucky for us, middlewares can take care of themselves. Adding flags to middleware -------------------------- Right now our middleware changes command output every time it is run. While that's pretty handy behavior, the command line is all about options. We can make our middleware even more reusable by adding self-contained optional behavior, via a flag:: import time from face import face_middleware, Flag, echo @face_middleware(provides=['start_time'], flags=[Flag('--echo-time', parse_as=True)]) def timing_middleware(next_, echo_time): start_time = time.time() ret = next_(start_time=start_time) if echo_time: echo('command executed in:', time.time() - start_time, 'seconds') return ret Now, every :class:`Command` that adds this middleware will automatically get a flag, ``--echo-time``. Just like other flags, its value will be injected into commands that need it. .. note:: **Weak Dependencies** - Middlewares that set defaults for keyword arguments are said to have a "weak" dependency on the associated injectable. If the command handler function, or another downstream middleware, do not accept the argument, the flag will not be parsed, or shown in generated help and error messages. This differs from the command handler function itself, which will accept arguments even when the function signature sets a default. Wrapping up ----------- I'd like to say that we were only scratching the surface of middlewares, but really there's not much more to them. They are an advanced feature of face, and a very powerful organizing tool for your code, but like many powerful tools, they are simple. You can use them in a wide variety of ways. Other useful middleware ideas: * Verbosity middleware - provides a ``verbose`` flag for downstream commands which can write additional output. * Logging middleware - sets up and provides an associated logger object for downstream commands. * Pipe middleware - Many CLIs are made for streaming. There are some semantics a middleware can help with, like breaking pipes. * KeyboardInterrupt middleware - Ctrl-C is a common way to exit programs, but Python generally spits out an ugly stack trace, even where a keyboard interrupt may have been valid. * Authentication middleware - provides an AuthenticatedUser object after checking environment variables and prompting for a username and password. * Debugging middleware - Because face middlewares are functions in a normal Python stack, it's easy to wrap downstream calls in a ``try``/``except``, and add a flag (or environment variable) that enables a ``pdb.post_mortem()`` to drop you into a debug console. The possibilities never end. If you build a middleware of particularly broad usefulness, consider contributing it back to the core! )Flag) make_chain get_arg_namesget_fbget_callable_labels)injectnext_args_cmd_subcmds_flags_posargs_ post_posargs_command_ subcommand_cJ[U5(a[USS5(agg)aNMostly for internal use, this function returns True if *target* is a valid face middleware. Middlewares can be functions wrapped with the :func:`face_middleware` decorator, or instances of a user-created type, as long as it's a callable following face's signature convention and has the ``is_face_middleware`` attribute set to True. is_face_middlewareNTF)callablegetattr)targets b/home/james-whalen/.local/share/pipx/venvs/semgrep/lib/python3.13/site-packages/face/middleware.py is_middlewarers$GF,@$GG Nc ^^^URS/5m[T[5(aT/m[URS/55mT(a,TH&n[U[5(aM[ SU-5e URSS5mU(a[ SUR 5-5eUUU4SjnU(a[U5(aU"U5$U$)aA decorator to mark a function as face middleware, which wraps execution of a subcommand handler function. This decorator can be called with or without arguments: Args: provides (list): An optional list of names, declaring which values be provided by this middleware at execution time. flags (list): An optional list of Flag instances, which will be automatically added to any Command which adds this middleware. optional (bool): Whether this middleware should be skipped if its provides are not required by the command. The first argument of the decorated function must be named "next_". This argument is a function, representing the next function in the execution chain, the last of which is the command's handler function. providesflagszexpected Flag object, not: %roptionalFz unexpected keyword arguments: %rcx>[UTS9 SUl[T5Ul[T5UlTUlU$)N)rT)check_middlewarerlist _face_flags_face_provides_face_optional)funcrrrs rdecorate_face_middleware1face_middleware..decorate_face_middlewares:1"&;"8n& r)pop isinstancestrr r TypeErrorkeysr)r$kwargsflagr%rrrs @@@rface_middlewarer.s$zz*b)H(C  : GR( )E DdD)) ?$ FGGzz*e,H :V[[]JKK '-- ##rcSn[[U5;a[U[U4-5e[U5[[/5- nUVs/sHn[ UR 5PM nn[ XX[5upxn U (aKS[U 5-n X[[U/55--n U (aU S[U 5-- n [U 5eU$s snf)akPerform basic validation of innermost function, wrap it in middlewares, and raise a :exc:`NameError` on any unresolved arguments. Args: middlewares (list): A list of middleware functions, prechecked by :func:`check_middleware`. innermost (callable): A function to be called after all the middlewares. preprovided (list): A list of built-in or otherwise preprovided injectables. Returns: A single function representing the whole middleware chain. This function is called automatically by :meth:`Command.prepare()` (and thus, :meth:`Command.run()`), and is more or less for internal use. z1argument %r reserved for middleware use only (%r)z.unresolved middleware or handler arguments: %rz: (%r provided but not resolvable, check middleware order.)) INNER_NAMEr NameErrorsetr r"rsortedsum) middlewares innermost preprovided_inner_exc_msg mw_builtinsmw mw_providesmw_chain mw_chain_argsmw_unresmsg avail_unress rget_middleware_chainrAs(IN]9--*i)@@AAk"S*%66K5@A[r4))*[KA(2;Yeo(p%HX>AQQC R4H0I"IJ  P[)* +Cn OBs Cc [U5(d[SU-5e[U5nSR[ U55nUR nU(d[SU<S[ <S35eUS[ :wa[SU<S[ <SUS<S 35eUR(a[SU<S UR<S 35eUR(a[SU<S UR<S 35eUbUO URn[[[5[U5-5nU(a[SU<S U<35eg )zCheck that a middleware callable adheres to function signature requirements. Called automatically by :class:`Command.add_middleware()` and elsewhere, this function raises :exc:`TypeError` if any issues are found. z'expected middleware %r to be a functionzmiddleware function z" must take at least one argument "z" as its first parameterrz must take argument "z" as the first parameter, not ""z1 may only take explicitly named arguments, not "*z2 may only take explicitly named arguments, not "**Nz0 provides conflict with reserved face builtins: ) rr*rjoinrargsr0varargsvarkwr"r r2_BUILTIN_PROVIDES)r$rfb func_label arg_names conflict_argss rrrs' D>>ADHII B,T23JI %z34 4|z!%z9Q<AB B zz9CRZZQR R xx:DbhhPQ Q$/xT5H5HH./#h-?@M9C]TU U r)N)__doc__ face.parserr face.sinterrrrrrr0rIrr.rArrrrRsRPfNN  &*z?0 )$X$N! r