Document v5 vs v4 and traits

README.md

@@ -8,17 +8,25 @@
 <!-- cargo-rdme start -->
 
 Provides an interface for querying the Podman REST API. Most of the interface is generated from
-the the official Podman swagger file. This crate adds a layer to make it possible to connect to
-the podman rest api over ssh to a unix socket and directly to a unix socket. Connections over
-ssh are commonly necessary on macOs where the container runtime runs in a virtual machine
-accessible over ssh.
+the official Podman swagger file. It can connect to the Podman API over ssh to a unix socket
+and directly to a unix socket. Connections over ssh are commonly necessary on macOs where the
+container runtime runs in a virtual machine accessible over ssh.
 
 
 ## API Compatibility
 
-This crate currently only works with version 5 of the podman API. There are suffucient
-differences between version 3, 4, and 5 that a lot of calls will not work in an older version.
-`podman --version` will reveal what version you are using.
+Use `podman --version` to determine what version of Podman you are using.
+
+### v5 Support
+
+This crate primarily works with version 5 of the Podman API. There are sufficient differences
+between version 3, 4, and 5 that a lot of calls will not work in an older version.
+
+### v4 Support (Not in good shape)
+
+While there is tentative v4 support it's in pretty terrible shape because the official Podman
+swagger file is missing all kinds of definitions. Some have been manually created, there is a
+lot more to do.
 
 ## Podman Socket
 
@@ -27,7 +35,14 @@ a socket you can connect to by default. You might need to enable the socket for
 connect to. For example on linux you might need to run something like this:
 
 ```sh
-systemctl --user enable --now podman.socket
+systemctl --user enable --now podman.socket // Enable the podman unix domain socket
+```
+
+On macOS you might need to invoke something like:
+
+```rust
+podman machine init // Create your podman virtual machine
+podman machine start // Start the machine
 ```
 
 ## Usage
@@ -39,7 +54,6 @@ On linux you might initialize a client like this
 ```rust
 #[cfg(feature = "v5")]
 use podman_rest_client::PodmanRestClient;
-use podman_rest_client::v5::Client;
 use podman_rest_client::Config;
 
 // Initialize a client
@@ -49,7 +63,7 @@ let client = PodmanRestClient::new(Config {
 }).await.unwrap();
 
 // Fetch a list of container images
-let images = client.images().image_list_libpod(None).await.unwrap();
+let images = client.v5().images().image_list_libpod(None).await.unwrap();
 ```
 ### MacOs
 
@@ -77,9 +91,39 @@ let config = Config::guess().await.unwrap();
 let client = PodmanRestClient::new(config).await.unwrap();
 
 // Fetch a list of container images
+let images = client.v5().images().image_list_libpod(None).await.unwrap();
+```
+
+### Traits
+
+If you import the `podman_rest_client::v5::Client` trait you don't need to invoke v5() and can 
+directly call the api functions like `client.images()`
+
+```rust
+#[cfg(feature = "v5")]
+use podman_rest_client::v5::Client;
 let images = client.images().image_list_libpod(None).await.unwrap();
 ```
 
+You can also use traits like `podman_rest_client::apis::Images` and directly call the
+individual request functions like so:
+
+```rust
+#[cfg(feature = "v5")]
+use podman_rest_client::v5::apis::Images;
+let images = client.image_list_libpod(None).await.unwrap();
+```
+
+
+## Features
+
+The default feature set is ["v5", "uds", "ssh"].
+
+- `ssh`: Support for connecting to a podman through an ssh server.
+- `uds`: Support for connecting to podman through a unix domain socket.
+- `v5`: Support for version 5 of the podman API
+- `v4`: Support for version 4 of the podman API. v4 is nowhere near ready for use.
+
 <!-- cargo-rdme end -->
 
 ## Swagger file modifications
@@ -89,15 +133,17 @@ issues and needs to be manually massaged. You can see the changes by comparing
 [swagger/swagger-v5.1.0.yaml](swagger/swagger-v5.1.0.yaml) against
 [swagger/swagger-v5.1.0.modified.yaml](swagger/swagger-v5.1.0.modified.yaml)
 
-### Renamed fields
+### v4
+
+#### Renamed fields
 
 * `definitions/Mount/properties/Target` renamed to `Destination`
 
-### Missing type info
+#### Missing type info
 
 * `definitions/ListContainer/properties/ExposedPorts` type set to `object`
 
-### Nullable fields
+#### Nullable fields
 
 It turns out golang is a bit loosey goosey with nils. The following fields were
 set to nullable:
@@ -109,7 +155,7 @@ set to nullable:
 I'm not sure, but it might make more sense to make all hashmap values as
 nullable by default in this project.
 
-### Client side defaults
+#### Client side defaults
 
 Some requests return extra streaming data with their responses by default. Our
 client doesn't support this, so we set up some client side overrides to set the

src/lib.rs

@@ -1,15 +1,23 @@
 //! Provides an interface for querying the Podman REST API. Most of the interface is generated from
-//! the the official Podman swagger file. This crate adds a layer to make it possible to connect to
-//! the podman rest api over ssh to a unix socket and directly to a unix socket. Connections over
-//! ssh are commonly necessary on macOs where the container runtime runs in a virtual machine
-//! accessible over ssh.
+//! the official Podman swagger file. It can connect to the Podman API over ssh to a unix socket
+//! and directly to a unix socket. Connections over ssh are commonly necessary on macOs where the
+//! container runtime runs in a virtual machine accessible over ssh.
 //!
 //!
 //! ## API Compatibility
 //!
-//! This crate currently only works with version 5 of the podman API. There are suffucient
-//! differences between version 3, 4, and 5 that a lot of calls will not work in an older version.
-//! `podman --version` will reveal what version you are using.
+//! Use `podman --version` to determine what version of Podman you are using.
+//!
+//! ### v5 Support
+//!
+//! This crate primarily works with version 5 of the Podman API. There are sufficient differences
+//! between version 3, 4, and 5 that a lot of calls will not work in an older version.
+//!
+//! ### v4 Support (Not in good shape)
+//!
+//! While there is tentative v4 support it's in pretty terrible shape because the official Podman
+//! swagger file is missing all kinds of definitions. Some have been manually created, there is a
+//! lot more to do.
 //!
 //! ## Podman Socket
 //!
@@ -18,7 +26,14 @@
 //! connect to. For example on linux you might need to run something like this:
 //!
 //! ```sh
-//! systemctl --user enable --now podman.socket
+//! systemctl --user enable --now podman.socket // Enable the podman unix domain socket
+//! ```
+//!
+//! On macOS you might need to invoke something like:
+//!
+//! ```
+//! podman machine init // Create your podman virtual machine
+//! podman machine start // Start the machine
 //! ```
 //!
 //! ## Usage
@@ -31,7 +46,6 @@
 //! #[cfg(feature = "v5")]
 //! # tokio_test::block_on(async {
 //! use podman_rest_client::PodmanRestClient;
-//! use podman_rest_client::v5::Client;
 //! use podman_rest_client::Config;
 //!
 //! // Initialize a client
@@ -41,7 +55,7 @@
 //! }).await.unwrap();
 //!
 //! // Fetch a list of container images
-//! let images = client.images().image_list_libpod(None).await.unwrap();
+//! let images = client.v5().images().image_list_libpod(None).await.unwrap();
 //! # })
 //! ```
 //! ### MacOs
@@ -69,7 +83,6 @@
 //! #[cfg(feature = "v5")]
 //! # tokio_test::block_on(async {
 //! # use podman_rest_client::PodmanRestClient;
-//! # use podman_rest_client::v5::Client;
 //! # use podman_rest_client::Config;
 //! // Setup the default configuration
 //! let config = Config::guess().await.unwrap();
@@ -78,9 +91,54 @@
 //! let client = PodmanRestClient::new(config).await.unwrap();
 //!
 //! // Fetch a list of container images
+//! let images = client.v5().images().image_list_libpod(None).await.unwrap();
+//! # })
+//! ```
+//!
+//! ### Traits
+//!
+//! If you import the `podman_rest_client::v5::Client` trait you don't need to invoke v5() and can 
+//! directly call the api functions like `client.images()`
+//!
+//! ```
+//! #[cfg(feature = "v5")]
+//! # tokio_test::block_on(async {
+//! # use podman_rest_client::PodmanRestClient;
+//! # use podman_rest_client::Config;
+//! use podman_rest_client::v5::Client;
+//! # let config = Config::guess().await.unwrap();
+//! # // Initialize a client
+//! # let client = PodmanRestClient::new(config).await.unwrap();
 //! let images = client.images().image_list_libpod(None).await.unwrap();
 //! # })
 //! ```
+//!
+//! You can also use traits like `podman_rest_client::apis::Images` and directly call the
+//! individual request functions like so:
+//!
+//! ```
+//! #[cfg(feature = "v5")]
+//! # tokio_test::block_on(async {
+//! # use podman_rest_client::PodmanRestClient;
+//! # use podman_rest_client::Config;
+//! use podman_rest_client::v5::apis::Images;
+//! # let config = Config::guess().await.unwrap();
+//! # // Initialize a client
+//! # let client = PodmanRestClient::new(config).await.unwrap();
+//! let images = client.image_list_libpod(None).await.unwrap();
+//! # })
+//! ```
+//!
+//!
+//! ## Features
+//!
+//! The default feature set is ["v5", "uds", "ssh"].
+//!
+//! - `ssh`: Support for connecting to a podman through an ssh server.
+//! - `uds`: Support for connecting to podman through a unix domain socket.
+//! - `v5`: Support for version 5 of the podman API
+//! - `v4`: Support for version 4 of the podman API. v4 is nowhere near ready for use.
+//!
 
 pub mod cli;
 mod config;

src/podman_rest_client.rs

@@ -53,6 +53,7 @@ impl PodmanRestClient {
  }
  }
 
+ #[cfg_attr(docsrs, doc(cfg(feature = "ssh")))]
  #[cfg(feature = "ssh")]
  pub async fn new_ssh(uri: String, key_path: Option<String>) -> Result<PodmanRestClient, Error> {
  let uri = hyper::Uri::from_str(&uri)?;
@@ -100,6 +101,7 @@ impl PodmanRestClient {
  self
  }
 
+ #[cfg_attr(docsrs, doc(cfg(feature = "v4")))]
  #[cfg(feature = "v4")]
  pub fn v4(&self) -> &dyn crate::v4::Client {
  self