Metadata-Version: 2.1
Name: fred-eppic
Version: 1.0.1
Summary: Fred-eppic is EPP Interactive Client.
Home-page: UNKNOWN
Author: Filip Úradník
Author-email: filip.uradnik@nic.cz
License: GPLv3+
Description: ==========
        Fred-eppic
        ==========
        
        Fred-eppic is EPP Interactive Client.
        
        Learn more about the project and our community on the `FRED's home page`__.
        
        .. _FRED: https://fred.nic.cz
        .. _Namespaces and Schemas: https://fred.nic.cz/documentation/html/EPPReference/SchemasNamespaces/index.html
        .. _Python Logging Dict Schema Wiki: https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
        
        __ FRED_
        
        
        Configuration
        =============
        
        You can configure EPPIC using a configuration file. On startup, EPPIC looks for
        a configuration file in two places. First, in your home directory, for a file
        called ``$HOME/.eppic.conf``. Only if it can't find it, it looks for
        ``/etc/eppic/eppic.conf``. If that file doesn't exist either, it loads its
        default config.
        
        Some config options, including the place where EPPIC looks for the
        configuration file, can be overriden with command-line arguments. Details are
        described in the `Command-line arguments`_ section.
        
        The configuration file is expected to be in the YAML__ format. It will be
        loaded using ``safe_load``, meaning it doesn't support any advanced YAML
        features, such as executing code.
        
        __ https://yaml.org/
        
        Session
        -------
        
        Before we take a look at the config file itself, we should talk about *sessions*.
        
        A session holds information and settings for your connection to the EPP server.
        The configuration allows you to specify multiple sessions, and then choose the
        one you want to use.
        
        If there are no sessions specified, you will startup with an error message. If
        there are sessions specified in your configuration file, and you don't say
        otherwise, the client will start up with first session loaded. If you want to
        choose another session, you can either use the ``--session=<session_id>``
        parameter when starting the client, or run the ``switch-session <session_id>``
        command when the client is running.
        
        The ``<session_id>`` argument can either be a number, meaning you want the
        ``n``-th session (from the top, numbers start from zero), or it can be a
        string, in which case EPPIC will start with a session with the matching
        ``alias``. If you didn't define an alias, ``username`` will be used instead.
        
        Config description
        --------------------
        
        Here, you can find the descriptions of all supported config options. There is a
        sample config file in the repository.
        
        ``sessions``
        ~~~~~~~~~~~~
        A list of defined sessions. Each session has following subkeys:
        
        * ``hostname``: Address of the server.
        * ``port``: Port over which to connect. Default value is ``700``.
        * ``cert_file``: Path to the certificate file. Default is ``None``.
        * ``key_file``: Path to the key file. Default is ``None``.
        * ``obj_uris``: A list of object namespace uris more information can be found
          in the `Namespaces and Schemas`_ section of FRED documentation.
          Default value is a list:
        
          * ``http://www.nic.cz/xml/epp/contact-1.6``
          * ``http://www.nic.cz/xml/epp/domain-1.4``
          * ``http://www.nic.cz/xml/epp/nsset-1.2``
          * ``http://www.nic.cz/xml/epp/keyset-1.3``
        
        * ``username``: The client id.
        * ``password``: Password corresponding to the client id.
        * ``verify`` *(optional)*: Whether or not to verify the certificate when
          communicating with the server. It is highly encouraged to keep this ``true``!
        * ``alias`` *(optional)*: The alias for this session. This can be used as an
          identifier for the session when using the ``switch-session`` command. If it
          is not specified, the username will be used.
        
        ``input_file`` *(optional)*
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Path to a file from which the client can take input. Default: stdin.
        
        ``input_format`` *(optional)*
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Format in which input is expected. Default: ``DEFAULT``. Accepted values are:
        
        * ``DEFAULT`` - described in the `Default command format`_ section.
        * ``JSON`` - on each line a dictionary containing one key - the command,
          with its subkeys being the arguments.
        * ``YAML`` - a valid YAML file (can have multiple documents), each document
          has one key - the command, with its subkeys being the arguments.
        
        ``output_format`` *(optional)*
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Format in which output is printed to stdout. Default: ``DEFAULT``. Accepted
        values are:
        
        * ``DEFAULT`` - described in the `Default command format`_ section.
        * ``JSON`` - on each line a dictionary containing one key - the command,
          with its subkeys being the arguments.
        * ``YAML`` - a valid YAML file (can have multiple documents), each document
          has one key - the command, with its subkeys being the arguments.
        
        ``logging`` *(optional)*
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        a dictionary specifying the logging configuration. For more info, read the
        `Python Logging Dict Schema Wiki`_. Defaults to basic Python configuration.
        
        ``interactive_input`` *(optional)*
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Advanced settings specifying details about interactive input.
        
        * ``autocomplete``: Whether or not to autocomplete when typing. Default:
          ``true``.
        * ``history_file_path``: Path to a file (doesn't need to exist) where
          history should be saved for autosuggestions. Default:
          ``$HOME/.cache/eppic/autosuggest_history``
        
        ``syntax_highlighting`` *(optional)*
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Turn syntax highlighting on/off for input and output. Default: ``true``.
        
        Command-line arguments
        ----------------------
        
        The client supports a number of command-line arguments. They are:
        
        * ``--session``: specifies ``<session_id>``. More on that in `Session`_.
        * ``--input-file``: overrides the ``input_file`` config option.
        * ``--config``: overrides the path to the config.
        
        If you only want to run one command, you can do so without opening the
        interactive client. You can simply add ``--`` after the last command-line
        argument, and add the command after that.
        
        For example:
        
        ::
        
          eppic --session=2 -- info-domain nic.cz
        
        would start EPPIC, login with the pre-defined session number 2, run the command
        ``info-domain nic.cz``, print its response, and then logout and exit.
        
        Default command format
        ----------------------
        
        The default command has the following format:
        
        ::
        
          <command-name> (--<argument-name>.<subargument-name>)(=)<argument-value> ...
        
        For example:
        
        ::
        
          info-domain --name=nic.cz
        
        When it is obvious what argument should follow, you can skip its name, and just say:
        
        ::
        
          info-domain nic.cz
        
        which is equivalent to the command above.
        
        It is, however, highly encouraged to write out all the names in commands with
        more complicated argument structure, especially commands which modify values on
        the server, to avoid ambiguity, and possibly avoid unwanted or unexpected
        behavior.
        
        There are both autocomplete and autosuggestion features in the interactive
        client, which are enabled by default. The autocompletion gives you a list of
        completions from the currently available arguments, and it should allow you to
        write much less than you would. It can also show you which arguments are
        optional, those are in parentheses. For some arguments, the values are from a
        given range. There it can even fill in the values for you.
        
        Some arguments allow you to insert a *list* of values. There you *have* to use
        the explicit names, and each argument from the list *has to* have a unique
        name. The autocompletion will automatically add numbers to the end of the names
        of list arguments, such as ``<argument-name>_1``. You can keep with this naming
        style, but you can put any numbers or letters after the original argument name.
        
        For example, the ``check-domain`` command has one list argument, ``names``.
        Let's say I want to check the domains ``nic.cz``, ``foo.cz`` and ``bar.cz``.
        Then I would say:
        
        ::
        
          check-domain --names_1=nic.cz --names_2=foo.cz --names_3=bar.cz
        
        as the autocompletion would suggest. But I can also say:
        
        ::
        
          check-domain --names_asd=nic.cz --names_fgh=foo.cz --names_jkl=bar.cz
        
        That doesn't make much sense to do in this context, but with commands with more
        complicated arguments, where you for example have list arguments inside list
        arguments, it can be useful to label the arguments the way you want them.
        
        Sometimes, you want to insert more complicated values, for example with spaces
        or equal signs. You can do that by using quotes (single or double). For
        example:
        
        ::
        
          sample-command --arg="very complicated value with -- and ="
        
        would result in ``arg``'s value being ``very complicated value with -- and =``.
        If you want to use quotes inside quotes, you can either use the other kind of
        quotes, or escape them using ``\\``. For example:
        
        ::
        
          sample-command --arg="very complicated value for \"name\" with \"--\" and \"=\" and \"\\\""
        
        would result in ``arg``'s value being ``very complicated value for "name" with "--" and "=" and "\"``.
        
        Other command formats
        ---------------------
        
        The default command format is meant mostly for the interactive client. If you
        want to use the client programmatically, it might be better to use one of the
        other formats, writing the input to a file and then running EPPIC with the
        ``--input-file`` command-line argument.
        
        You can set the input format in the config file, apart from ``DEFAULT`` you can
        choose ``JSON`` and ``YAML``.
        
        ``JSON`` format requires that each line in the input file is a valid JSON
        document containing exactly one key, which contains the arguments as its
        subkeys. More complicated arguments should be inserted as nested dictionaries.
        For example:
        
        ::
        
          {"info-domain": {"name": "nic.cz"}}
        
        If a command has no arguments, use ``{}``.
        
        ``YAML`` format is a bit different, and more user-friendly, because YAML,
        unlike JSON, allows `multiple documents in one file`__. When writing a command
        in the ``YAML`` format, each document in the file should have exactly one key -
        the name of the command, and its subkeys should be the arguments. For example:
        
        ::
        
          ---
          info-domain:
            name: nic.cz
          ...
        
        __ https://yaml.org/spec/1.2.2/#structures
        
        Help command
        ------------
        
        There is a built-in help command, which gives you short help about a command
        and its parameters. Simpy type:
        ::
        
         help <command-name> (<possible arguments> ...)
        
        The help is designed to work even if you're in the middle of writing a command,
        and you want to be reminded about a parameter's meaning, for example. In that
        case you can simply pre-pend what you've already written with ``help``, and
        you'll get an answer.
        
        If you don't want to type as much, you can use the shortcut ``ctrl-space``,
        which calls help with what you've already written. If you use this shortcut and
        want to get back to what you were writing, you can simply hit the ``up`` key
        twice.
        
        If you want to get help for more commands at once, you can give it partial
        names, too. For example, if you wanted to get help for all ``info`` commands,
        you can say:
        ::
        
          help info
        
        and you'll get help for all commands containing ``info`` in their name.
        
        And finally, if you want to get help for all available commands, you can simply
        say ``help``, and it will give you everything it has.
        
        Public API specification
        ========================
        
        Public API of this application marked as compatible for the purpose of semantic versioning is a command-line interface.
        Specifically:
        
        * Command names, arguments and behaviour, regardless of the input format.
        * Structure of command outputs, with respect to the format used, in all formats except for the text output.
        * Structure of the configuration file.
        
        Changes excluded from public API compatibility:
        
        * Any features marked as experimental.
        * Command behaviour changes caused by changes on the EPP server, especially changes in EPP schemas.
        * Interactive prompt features, such as history, autocompletion and command validation.
        
        ChangeLog
        =========
        
        .. contents:: Releases
           :backlinks: none
           :local:
        
        Unreleased
        ----------
        
        
        1.0.1 (2022-12-21)
        ------------------
        
        * Fix nested dataclass attributes (#66).
        * Output in unicode encoding (#67).
        
        1.0.0 (2022-12-15)
        ------------------
        
        * Add support for Python 3.11.
        * Suggest required args first (#59).
        * Tweak prompt validation (#62).
        * Update session defaults (#54).
        * Fix get-results output (#60).
        * Fix representing enums in output (#56).
        * Fix subarguments' required flag (#58).
        
        * Add ``ArgumentField`` object (#63, #58).
        * Public API specification (#64).
        * Update project setup.
        * Fix typing and tests (#52).
        
        0.1.2 (2022-10-05)
        ------------------
        
        * Restrict supported pydantic versions.
        
        0.1.1 (2022-09-29)
        ------------------
        
        A number of changes and fixes for the initial version.
        
        0.1.0 (2022-09-19)
        ------------------
        
        Initial version.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: ~=3.8
Provides-Extra: quality
Provides-Extra: test
Provides-Extra: types
