From 49ef5188ada88f8f2f6cfd858b8baf7ac6b27760 Mon Sep 17 00:00:00 2001 From: florian <f.spreckelsen@inidscale.com> Date: Wed, 14 Jul 2021 10:44:06 +0200 Subject: [PATCH] DOC: Add docstrings --- src/CaosDB.jl | 192 ++++++++++++++++++++++++++++++++++---------------- 1 file changed, 130 insertions(+), 62 deletions(-) diff --git a/src/CaosDB.jl b/src/CaosDB.jl index 51a437f..dc16c33 100644 --- a/src/CaosDB.jl +++ b/src/CaosDB.jl @@ -26,9 +26,12 @@ module CaosDB module Info """ -Struct containing version information of the CaosDB server. +Struct containing version information of the CaosDB server. Meant +mainly for internal usage; use `CaosDB.Connection.get_version_info` or +`CaosDB.Connection.print_version_info` to retrieve the version of the +connected CaosDB server. """ -mutable struct VersionInfo +mutable struct _VersionInfo major::Cint minor::Cint @@ -36,7 +39,7 @@ mutable struct VersionInfo pre_release::Cstring build::Cstring - VersionInfo() = new() + _VersionInfo() = new() end @@ -70,12 +73,15 @@ end # Utility module Authentication """ -Struct containing a pointer to the wrapped cpp authenticator class. +Struct containing a pointer to the wrapped cpp authenticator +class. Meant for internal use; call a +`CaosDB.Authentication.create_<authenticator>` function to create an +authenticator object from a configuration. """ -mutable struct Authenticator +mutable struct _Authenticator wrapped_authenticator::Ptr{Cvoid} - function Authenticator() + function _Authenticator() auth = new() # force this to point to C_NULL after initialization auth.wrapped_authenticator = C_NULL @@ -85,8 +91,8 @@ mutable struct Authenticator ccall( (:caosdb_authentication_delete_authenticator, "libccaosdb"), Cint, - (Ref{Authenticator},), - Ref{Authenticator}(t), + (Ref{_Authenticator},), + Ref{_Authenticator}(t), ) end end @@ -94,17 +100,27 @@ mutable struct Authenticator end end +""" + create_plain_password_authenticator( + username::AbstractString, + password::AbstractString, + ) + +Return an authenticator object that contains a wrapped cpp +plain-password authenticator configured with `username` and +`password`. +""" function create_plain_password_authenticator( username::AbstractString, password::AbstractString, ) - auth = Ref{Authenticator}(Authenticator()) + auth = Ref{_Authenticator}(_Authenticator()) err_code = ccall( (:caosdb_authentication_create_plain_password_authenticator, "libccaosdb"), Cint, - (Ref{Authenticator}, Cstring, Cstring), + (Ref{_Authenticator}, Cstring, Cstring), auth, username, password, @@ -126,13 +142,17 @@ module Connection using ..CaosDB +export connect + """ -Struct containing the actual connection to a CaosDB server. +Struct containing the actual connection to a CaosDB server. Meant for +internal use; call a `CaosDB.Connection.create_<connection>` function +to create an connection object from a configuration. """ -mutable struct CaosDBConnection +mutable struct _Connection wrapped_connection::Ptr{Cvoid} - function CaosDBConnection() + function _Connection() conn = new() conn.wrapped_connection = C_NULL function f(t) @@ -140,8 +160,8 @@ mutable struct CaosDBConnection ccall( (:caosdb_connection_delete_connection, "libccaosdb"), Cint, - (Ref{CaosDBConnection},), - Ref{CaosDBConnection}(t), + (Ref{_Connection},), + Ref{_Connection}(t), ) end end @@ -151,12 +171,14 @@ end """ Struct containing a pointer to the wrapped cpp class providing the -certificate provider. +certificate provider. Meant for internal use; call a +`CaosDB.Connection.create_<certificate_provider>` function to create +an certificate-provider object from a configuration. """ -mutable struct CertificateProvider +mutable struct _CertificateProvider wrapped_certificate_provider::Ptr{Cvoid} - function CertificateProvider() + function _CertificateProvider() prov = new() prov.wrapped_certificate_provider = C_NULL function f(t) @@ -164,8 +186,8 @@ mutable struct CertificateProvider ccall( (:caosdb_connection_delete_certificate_provider, "libccaosdb"), Cint, - (Ref{CertificateProvider},), - Ref{CertificateProvider}(t), + (Ref{_CertificateProvider},), + Ref{_CertificateProvider}(t), ) end end @@ -175,12 +197,14 @@ end """ Struct containing a pointer to the wrapped cpp class for storing the -connection configuration. +connection configuration. Meant for internal use; call a +`CaosDB.Connection.create_<configuration>` function to create +an connection-configuration object from a configuration. """ -mutable struct Configuration +mutable struct _Configuration wrapped_connection_configuration::Ptr{Cvoid} - function Configuration() + function _Configuration() config = new() config.wrapped_connection_configuration = C_NULL function f(t) @@ -188,8 +212,8 @@ mutable struct Configuration ccall( (:caosdb_connection_delete_connection_configuration, "libcaosdb"), Cint, - (Ref{Configuration},), - Ref{Configuration}(t), + (Ref{_Configuration},), + Ref{_Configuration}(t), ) end end @@ -200,17 +224,17 @@ end """ create_pem_file_certificate_provider(path::AbstractString) -Return a `CertificateProvider` for the pem certificate located at +Return a `_CertificateProvider` for the pem certificate located at `path`. """ function create_pem_file_certificate_provider(path::AbstractString) - cert_provider = Ref{CertificateProvider}(CertificateProvider()) + cert_provider = Ref{_CertificateProvider}(_CertificateProvider()) err_code = ccall( (:caosdb_connection_create_pem_file_certificate_provider, "libccaosdb"), Cint, - (Ref{CertificateProvider}, Cstring), + (Ref{_CertificateProvider}, Cstring), cert_provider, path, ) @@ -229,8 +253,8 @@ end create_tls_connection_configuration( host::AbstractString, port::Cint, - authenticator::Ref{CaosDB.Authentication.Authenticator}, - provider::Ref{CertificateProvider} + authenticator::Ref{CaosDB.Authentication._Authenticator}, + provider::Ref{_CertificateProvider} ) Return a TLS connection configuration with authentication. @@ -238,21 +262,21 @@ Return a TLS connection configuration with authentication. function create_tls_connection_configuration( host::AbstractString, port::Cint, - authenticator::Ref{CaosDB.Authentication.Authenticator}, - provider::Ref{CertificateProvider}, + authenticator::Ref{CaosDB.Authentication._Authenticator}, + provider::Ref{_CertificateProvider}, ) - config = Ref{Configuration}(Configuration()) + config = Ref{_Configuration}(_Configuration()) err_code = ccall( (:caosdb_connection_create_tls_connection_configuration, "libccaosdb"), Cint, ( - Ref{Configuration}, + Ref{_Configuration}, Cstring, Cint, - Ref{CaosDB.Authentication.Authenticator}, - Ref{CertificateProvider}, + Ref{CaosDB.Authentication._Authenticator}, + Ref{_CertificateProvider}, ), config, host, @@ -273,12 +297,12 @@ end function create_insecure_connection_configuration(host::AbstractString, port::Cint) - config = Ref{Configuration}(Configuration()) + config = Ref{_Configuration}(_Configuration()) err_code = ccall( (:caosdb_connection_create_insecure_connection_configuration, "libccaosdb"), Cint, - (Ref{Configuration}, Cstring, Cint), + (Ref{_Configuration}, Cstring, Cint), config, host, port, @@ -294,18 +318,18 @@ function create_insecure_connection_configuration(host::AbstractString, port::Ci end """ - create_connection(config::Ref{Configuration}) + create_connection(config::Ref{_Configuration}) Return a connection based on the given `config`. """ -function create_connection(config::Ref{Configuration}) +function create_connection(config::Ref{_Configuration}) - connection = Ref{CaosDBConnection}(CaosDBConnection()) + connection = Ref{_Connection}(_Connection()) err_code = ccall( (:caosdb_connection_create_connection, "libccaosdb"), Cint, - (Ref{CaosDBConnection}, Ref{Configuration}), + (Ref{_Connection}, Ref{_Configuration}), connection, config, ) @@ -321,19 +345,19 @@ function create_connection(config::Ref{Configuration}) end """ - get_version_info(con::Ref{CaosDBConnection}) + get_version_info(con::Ref{_Connection}) Return the version of the CaosDB server that `con` is connected to. """ -function get_version_info(con::Ref{CaosDBConnection}) +function get_version_info(con::Ref{_Connection}) - info = Ref{CaosDB.Info.VersionInfo}(CaosDB.Info.VersionInfo()) + info = Ref{CaosDB.Info._VersionInfo}(CaosDB.Info._VersionInfo()) err_code = ccall( (:caosdb_connection_get_version_info, "libccaosdb"), Cint, - (Ref{CaosDB.Info.VersionInfo}, Ref{CaosDBConnection}), + (Ref{CaosDB.Info._VersionInfo}, Ref{_Connection}), info, con, ) @@ -350,12 +374,12 @@ function get_version_info(con::Ref{CaosDBConnection}) end """ - print_version_info(con::Ref{CaosDBConnection}) + print_version_info(con::Ref{_Connection}) Retrieve the version info for the CaosDB server `con` is connected to, and print the version in a nice message. """ -function print_version_info(con::Ref{CaosDBConnection}) +function print_version_info(con::Ref{_Connection}) # Dereference to access the fields info = get_version_info(con)[] @@ -372,41 +396,87 @@ function print_version_info(con::Ref{CaosDBConnection}) end -function connect( - host::AbstractString = nothing, - port_str::AbstractString = nothing, - cacert::AbstractString = nothing, - username::AbstractString = nothing, - password::AbstractString = nothing, +""" + function connect([; + host::AbstractString="", + port_str::AbstractString="undefined", + cacert::AbstractString="", + username::AbstractString="", + password::AbstractString="undefined"] + ) + +Return a connection object created for the given `host`:`port` with an +SSL certificate located at `cacert` with the given credentials. + +# Extended help + +!!! info + + Because of type-stability, and since an empty string may be a + valid password, the value of `password`, for which it is fetched + from an environmental variable, is "undefined". This means that if + you absolutely must use "undefined" as your password, you have to + specify it via the `CAOSDB_PASSWORD` variable. + +# Arguments +- `host::AbstractString=""`: The hostname of the CaosDB server. If + none is provided, the `CAOSDB_SERVER_HOST` environmental variable is + used instead. If that's not defined, "localhost" is used. +- `port_str::AbstractString="undefined"`: The port of the CaosDB + server, given as string. If none is provided, the + `CAOSDB_SERVER_GRPC_PORT_HTTPS` environmental variable is used + instead. If that's not defined, "8443" is used. The default value is + "undefined" rather than an empty string because an empty string + could be a valid port, too, i.e. the CaosDB server is available at + `host` without a port. +- `cacert::AbstractString=""`: The path to the SSL certificate of the + CaosDB server. If none is provided, the `CAOSDB_SERVER_CERT` + environmental variable is used instead. +- `username::AbstractString=""`: The username with which to log in + into the CaosDB server. If none is provided, the `CAOSDB_USER` + environmental variable is used instead. If that's not defined, + "admin" is used. +- `password::AbstractString="undefined"`: The password with which to + log in into the CaosDB server. If none is provided, the + `CAOSDB_PASSWORD` environmental variable is used instead. If that's + not defined, "caosdb" is used. The default value is "undefined" + rather than an empty string to allow an empty password. +""" +function connect(; + host::AbstractString="", + port_str::AbstractString="undefined", + cacert::AbstractString="", + username::AbstractString="", + password::AbstractString="undefined" ) - if host == nothing + if host == "" host = CaosDB.Utility.get_env_var("CAOSDB_SERVER_HOST", "localhost") end - if port_str == nothing + if port_str == "undefined" - port = CaosDB.Utility.get_env_var("CAOSDB_SERVER_GRPC_PORT_HTTPS", "8443") + port_str = CaosDB.Utility.get_env_var("CAOSDB_SERVER_GRPC_PORT_HTTPS", "8443") end port = parse(Cint, port_str) - if cacert == nothing + if cacert == "" cacert = CaosDB.Utility.get_env_var("CAOSDB_SERVER_CERT") end - if username == nothing + if username == "" username = CaosDB.Utility.get_env_var("CAOSDB_USER", "admin") end - if password == nothing + if password == "undefined" password = CaosDB.Utility.get_env_var("CAOSDB_PASSWORD", "caosdb") @@ -423,8 +493,6 @@ function connect( end -export connect - end # Connection module Entity end -- GitLab