DPY-3029 is undocumented

[doerwalter]

1. What is the link to the documentation section that needs improving?

https://python-oracledb.readthedocs.io/en/latest/user_guide/troubleshooting.html#dpyerr

2. Describe the confusion

I was using the program argument to oracledb.connect() like this:

🐚 ~ ❯ python
Python 3.13.0 (main, Oct  7 2024, 05:02:14) [Clang 15.0.0 (clang-1500.3.9.4)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys, oracledb
>>> db = oracledb.connect("...", program=f"{sys.executable}: foo.py")
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    db = oracledb.connect("...", program=f"{sys.executable}: foo.py")
  File "/Users/walter/pyvenvs/default/lib/python3.13/site-packages/oracledb/connection.py", line 1194, in connect
    return conn_class(dsn=dsn, pool=pool, params=params, **kwargs)
  File "/Users/walter/pyvenvs/default/lib/python3.13/site-packages/oracledb/connection.py", line 552, in __init__
    dsn = params_impl.process_args(dsn, kwargs, thin)
  File "src/oracledb/impl/base/connect_params.pyx", line 481, in oracledb.base_impl.ConnectParamsImpl.process_args
  File "src/oracledb/impl/base/connect_params.pyx", line 100, in oracledb.base_impl.ConnectParamsImpl.set
  File "src/oracledb/impl/base/utils.pyx", line 194, in oracledb.base_impl._set_str_param
  File "/Users/walter/pyvenvs/default/lib/python3.13/site-packages/oracledb/errors.py", line 195, in _raise_err
    raise error.exc_type(error) from cause
oracledb.exceptions.NotSupportedError: DPY-3029: "program" includes characters that are not allowed

However DPY-3029 ist not documented on https://python-oracledb.readthedocs.io/en/latest/user_guide/troubleshooting.html#dpyerr

3. Suggest changes that would help

https://python-oracledb.readthedocs.io/en/latest/user_guide/troubleshooting.html#dpyerr should document DPY-3029. It should state what the allowed characters are.

[cjbj]

Thanks for the idea.

[cjbj]

Doc for this has been created and will be pushed to GitHub in the near future.