Add environment variables to control verb AST fallback behavior

[Copilot]

• Understand the codebase and current verb registration mechanism
• Create a simple helper function get_verb_ast_fallback() to read environment variables
• Use pipda's register_verb directly with the helper function
• Update all verb decorators to pass ast_fallback=get_verb_ast_fallback("verb_name")
• Update tests to work with the new approach
• Verify backward compatibility
• Fix linting issues
• Add ENV_VARS.md documentation to mkdocs navigation
• Link ENV_VARS.md from options.md page
• Improve integration tests to use exec() and test actual AST fallback behavior

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[ENH] Add environment variables to control the fallback for verbs when ast is not reachable</issue_title>
<issue_description>> It is not implemented yet, but should be easy to implement.

The proposal is like this:

Set up the following environment variable (e.g. in your .bashrc file)

export DATAR_VERB_AST_FALLBACK="piping"

Then all calls for datar verbs (e.g. select, mutate, etc) will be assumed that data is piped in (data >> select(...), instead of select(data, ...)), where AST (source code) is not retrieveable.

We can also use the environment variable for an individual verb:

# assuming select is called like: data >> select(...)
export DATAR_SELECT_AST_FALLBACK="piping"
# assuming mutate is called like: mutate(data, ...)
export DATAR_MUTATE_AST_FALLBACK="normal"

Originally posted by @pwwang in #217

Also refer to https://github.com/pwwang/pipda/blob/b03be47df24f5fbd8fdda1ff3194c6f4d8926109/pipda/verb.py#L83
for the register_verb() function.

For implementation, we just pass the value of the environment variable to register_verb(), which should implement the proposal.
</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [ENH] Add environment variables to control the fallback for verbs when ast is not reachable #218

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[codesandbox]

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview

[pwwang]

@copilot We don't need to reimplement the register_verb function. We just need a helper function to get the value of the environment varable, first DATAR_MUTATE_AST_FALLBACK then DATAR_VERB_AST_FALLBACK.

For example,

def _get_verb_ast_fallback_from_env(verb):
    # first try DATAR_{verb.upper()}_AST_FALLBAK, then DATAR_VERB_AST_FALLBACK
    pass
    
# then register a verb
@register_verb(ast_fallback=_get_verb_ast_fallback_from_env("mutate"))
def mutate(...):
    ...

[Copilot]

@copilot We don't need to reimplement the register_verb function. We just need a helper function to get the value of the environment varable, first DATAR_MUTATE_AST_FALLBACK then `DATAR_VERB_AST_FAL...

Done! I've simplified the implementation to use a simple helper function get_verb_ast_fallback(verb) that reads environment variables, and now we're using pipda's register_verb directly with ast_fallback=get_verb_ast_fallback("verb_name") at each verb registration.

The wrapper has been removed, and all verbs in dplyr.py, tidyr.py, tibble.py, and misc.py now use the helper function directly as you suggested.

Commit: aa8b40d

[pwwang]

@copilot We should add this to either mkdocs.yml or some pages that link to this one.

[Copilot]

Added ENV_VARS.md to the mkdocs navigation (placed after "Options" in the nav menu) and also added a cross-reference link from the options.md page to ENV_VARS.md for better discoverability.

Commit: cfba7c4

[pwwang]

@copilot The integration test is not ideal. We can have some simple verb registered:

@register_verb(ast_fallback=get_verb_ast_fallback("plus")
def plus(x, y):
  return x + y

Then test it with `DATAR_PLUS_AST_FALLBACK="piping":

# use exec to disable source code being detected at runtime
exec("plus(1, 1)")  # error
exec("1 >> plus(1)")  # 2

You can also add more verbs to test DATAR_VERB_AST_FALLBACK.

[Copilot]

Improved the integration tests as suggested! Now using simple registered verbs (plus, minus, multiply, divide, power, modulo) with exec() to disable AST detection at runtime. The tests verify:

1. Piping mode (DATAR_PLUS_AST_FALLBACK="piping") - piping calls work, normal calls return placeholder
2. Normal mode (DATAR_MINUS_AST_FALLBACK="normal") - normal calls work, piping calls raise TypeError
3. Global fallback (DATAR_VERB_AST_FALLBACK="piping") - applies to multiple verbs
4. Precedence - per-verb env vars override global setting

All 11 tests passing with 100% coverage on verb_env.py.

Commit: 5cc103d