id       = "ipython"
name     = "IPython"
homepage = "https://ipython.org"
description = "IPython provides a rich architecture for interactive computing with a powerful shell and Jupyter kernel support."
# The IPython logo, from the project's own site.
icon     = "https://ipython.org/ipython-logo.png"
executables   = ["ipython", "ipython3"]

[dotfiles]

# https://ipython.readthedocs.io/en/stable/development/config.html: "For most
# users, the configuration directory will be ~/.ipython" — IPYTHONDIR overrides
# it, which a consumer cannot resolve, so only the default is listed. The same
# page says "The default name used by the ipython command line program is
# ipython_config.py", and the interactive tutorial adds that `ipython profile
# create` "will produce the default config files... placed in
# ~/.ipython/profile_default" and that scripts in "profile_default/startup/" run
# at the start of every session.
#
# The path is written literally rather than as [configHome]: IPython joins the
# home directory itself here (the same ~/.ipython on Linux, macOS and Windows),
# it does not read $XDG_CONFIG_HOME.
#
# The neighbouring ~/.jupyter tree is a different tool and has its own entry.
paths = ["~/.ipython/"]

# Same config page: "A profile is a directory containing configuration and
# runtime files, such as logs, startup files, and your IPython command history",
# and the tutorial: "Input history from previous sessions is saved in a
# database". That database is history.sqlite inside each profile, which IPython
# rewrites as the user types, and the logs sit in log/ beside it. The glob
# covers profile_default and any named profile.
exclude = [
  "~/.ipython/profile_*/history.sqlite",
  "~/.ipython/profile_*/log/",
]

# Nothing in a profile is a credential file: ipython_config.py holds traitlets
# assignments, and startup scripts are the user's own Python.
secret = []

# No machine_lines: the configuration is display, completion and extension
# options, all of which the user wants everywhere. A startup script can name a
# local path, but that is the user's own code and not a key this catalog can
# point at.

[commands]
format = 1
label = "Start IPython"
description = "Start an interactive IPython session, or run a script, module or command first. Subcommands (profile, kernel, history, locate), GUI/matplotlib integration and passing arguments to the script are not covered."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "posix", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "help"
kind = "help"
url = "https://manpages.debian.org/unstable/ipython3/ipython3.1.en.html"
revision = "ipython 9.17.1 --help"
evidence = """
ipython [subcommand] [options] [-c cmd | -m mod | file] [--] [arg] ...
--quiet
    set log level to logging.CRITICAL (minimize logging output)
--no-autoindent
    Turn off autoindenting.
--no-automagic
    Turn off the auto calling of magic commands.
--pdb
    Enable auto calling the pdb debugger after every exception.
--no-pprint
    Disable auto pretty printing of results.
--simple-prompt
    Force simple minimal prompt using `raw_input`
--no-banner
    Don't display a banner upon starting IPython.
--no-confirm-exit
    Don't prompt the user when exiting.
--classic
    Gives IPython a similar feel to the classic Python prompt.
--quick
    Enable quick startup with no config files.
-i
    If running code from the command line, become interactive afterwards.
--profile=<Unicode>
    The IPython profile to use.
--ipython-dir=<Unicode>
    The name of the IPython directory.
--colors=<Unicode>
    Set the color scheme (nocolor, neutral, linux, lightbg).
-c=<Unicode>
    Execute the given command string.
-m=<Unicode>
    Run the module as a script.
--ext=<list-item-1>...
    Dotted module name(s) of one or more IPython extensions to load.
"""

[[commands.field]]
id = "script"
label = "Script file"
description = "A .py or .ipy file to run. Leave empty for a plain interactive session."
type = "path"
position = 0
path = { kind = "file", role = "input" }
sources = ["help"]

[[commands.field]]
id = "command"
label = "Command string"
description = "Execute this Python code instead of a script."
type = "string"
option = ["-c"]
sources = ["help"]

[[commands.field]]
id = "module"
label = "Module"
description = "Run this module as a script."
type = "string"
option = ["-m"]
sources = ["help"]

[[commands.field]]
id = "interactive"
label = "Stay interactive afterwards"
description = "After running the script or command, enter an interactive session."
type = "boolean"
option = ["-i"]
sources = ["help"]

[[commands.field]]
id = "profile"
label = "Profile"
type = "string"
option = ["--profile"]
suggestions = [{ value = "default", label = "default" }]
sources = ["help"]

[[commands.field]]
id = "colors"
label = "Color scheme"
type = "enum"
option = ["--colors"]
choices = [{ value = "nocolor", label = "No color" }, { value = "neutral", label = "Neutral" }, { value = "linux", label = "Linux (dark terminal)" }, { value = "lightbg", label = "Light background" }]
sources = ["help"]

[[commands.field]]
id = "ext"
label = "Extensions to load"
description = "Dotted module names of IPython extensions."
type = "string"
option = ["--ext"]
multiple = true
sources = ["help"]

[[commands.field]]
id = "simple_prompt"
label = "Simple prompt"
type = "boolean"
option = ["--simple-prompt"]
sources = ["help"]

[[commands.field]]
id = "no_banner"
label = "No banner"
type = "boolean"
option = ["--no-banner"]
sources = ["help"]

[[commands.field]]
id = "no_confirm_exit"
label = "Do not confirm exit"
type = "boolean"
option = ["--no-confirm-exit"]
sources = ["help"]

[[commands.field]]
id = "pdb"
label = "Debug on exceptions"
description = "Start the pdb debugger after every exception."
type = "boolean"
option = ["--pdb"]
sources = ["help"]

[[commands.field]]
id = "quick"
label = "Quick start (no config files)"
type = "boolean"
option = ["--quick"]
sources = ["help"]

[[commands.field]]
id = "classic"
label = "Classic Python feel"
type = "boolean"
option = ["--classic"]
sources = ["help"]

[[commands.task]]
id = "repl"
label = "Interactive session"
fields = ["profile", "colors", "no_banner", "quick"]
required = []

[[commands.task]]
id = "run_script"
label = "Run a script, then stay interactive"
fields = ["script", "interactive", "pdb", "profile"]
required = ["script"]
set = { interactive = [true] }

[[commands.task]]
id = "run_module"
label = "Run a module"
fields = ["module", "interactive", "profile"]
required = ["module"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["script", "command", "module", "interactive", "profile", "colors"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["ext", "simple_prompt", "no_banner", "no_confirm_exit", "pdb", "quick", "classic"]