wpypress 0.2.0
A versatile Python library for seamless interaction with the WordPress REST API, including built-in SEO features and more.
Requires Python: >=3.6

# wpypress

`wpypress` is a Python library designed for interacting with the WordPress REST API. It simplifies the process of managing posts, pages, media, categories, tags, WooCommerce products and SEO settings on WordPress sites.

## Features

- **Post Management**: Create, update, delete, and list posts.
- **Page Management**: Create, update, delete, and list pages.
- **Media Management**: Upload, update, delete, and list media items.
- **Category & Tag Management**: Create, update, delete, and list categories and tags.
- **SEO Management**: Manage SEO settings using the Yoast SEO plugin.
- **Ecommerce products**: Manage products and product categories using WooCommerce APIs.

## Installation

To install `wpypress`, simply use pip:

```bash
pip install wpypress
```

## Usage

### Initialization

To start using the library, first, initialize the `WPClient` with your WordPress site credentials:

```python
from wpypress import WPClient

wp = WPClient(
    base_url="https://your-wordpress-site.com",
    username="admin",
    password="your-password"
)
```

### Posts

#### Fetch Posts

Retrieve the first page of posts:

```python
posts, pagination = wp.posts.list(params={'per_page': 10, 'page': 1})
print(f"Total posts: {pagination['total']}")
print(f"Total pages: {pagination['total_pages']}")
print(f"Current page: {pagination['page']}\n")
```

#### Fetch a Post

Retrieve a post by ID:

```python
post = wp.posts.get(200) # WordPress Post ID
print(f"Post Title: {post['title']['rendered']}")
```

Retrieve a post by slug:

```python
post = wp.posts.get(slug='my-post-slug') # WordPress Post Slug
print(f"Post Title: {post[0]['title']['rendered']}")
```

#### Create a Post

Create a new post with categories and tags:

```python
post = wp.posts.create(
    title="My New Post",
    content="This is the content.",
    status="publish",
    categories=[2],
    tags=[5, 6],
    featured_media=15
)
```

#### Delete a Post

To delete a post, use:

```python
wp.posts.delete(123, force=True)
```

### Pages

#### Create a New Page

To create a new page:

```python
page = wp.pages.create(
    title="About Us",
    content="This is our about page.",
    excerpt="About page",
    status="publish"
)
```

### Media

#### Upload an Image

To upload a media item, execute:

```python
media = wp.media.upload(
    file_path='./images/photo.jpg',
    title='My Photo',
    alt_text='A beautiful photo',
    description='Uploaded via REST APIs'
)
```

### Categories

#### Create a Category

```python
new_category = wp.categories.create(
    name="Tech News",
    slug="tech-news",
    description="Technology related articles"
)
```

### Tags

#### Create a Tag

```python
new_tag = wp.tags.create(
    name="Python",
    slug="python",
    description="All posts about Python"
)
```

### SEO

#### Update Post SEO (Yoast SEO)

Ensure your site has the Yoast SEO plugin activated to manage SEO settings easily:

```python
if wp.seo.is_yoast():
    wp.seo.update(
        post_id=456,
        title="Page SEO Title",
        description="Meta description for the page.",
        og_title="OpenGraph Title for Page",
        og_description="OpenGraph Description for Page",
        type="page"
    )
```

### Products

#### Check if WooCommerce is Installed

Before performing operations related to WooCommerce, you can check if WooCommerce is installed on your WordPress site:

```python
if wp.products.isWoocommerce():
    print("WooCommerce is installed.")
else:
    print("WooCommerce is not installed.")
```

#### Fetch Products

Retrieve the list of products:

```python
products = wp.products.list(params={'per_page': 10, 'page': 1})
print(f"Total products: {len(products)}")
```

#### Fetch a Product

Retrieve a product by ID:

```python
product = wp.products.get(100) # WooCommerce Product ID
print(f"Product Name: {product['name']}")
```

#### Create a Product

Create a new simple product:

```python
product = wp.products.create(
    name="New Product",
    type="simple",
    regular_price="19.99",
    description="This is a simple product."
)
```

#### Update a Product

Update an existing product:

```python
updated_product = wp.products.update(
    product_id=100,
    regular_price="24.99",
    description="Updated product description."
)
```

#### Delete a Product

To delete a product:

```python
wp.products.delete(100, force=True)
```

### Product Categories

The `ProductCategoriesEndpoint` allows you to manage WooCommerce product categories via the WooCommerce REST API.

#### List Product Categories

Retrieve a list of product categories with optional filtering and pagination:

```python
categories, pagination = wp.product_categories.list(params={'per_page': 10, 'page': 1})
print(f"Total categories: {pagination['total']}")
print(f"Total pages: {pagination['total_pages']}")
print(f"Current page: {pagination['page']}\n")
```

#### Fetch a Product Category

Retrieve a product category by ID:

```python
category = wp.product_categories.get(25) # WooCommerce Category ID
print(f"Category Name: {category['name']}")
```

#### Create a Product Category

Create a new product category:

```python
new_category = wp.product_categories.create(
    name="Accessories",
    slug="accessories",
    description="Various fashion accessories"
)
```

#### Update a Product Category

Update an existing product category:

```python
updated_category = wp.product_categories.update(
    category_id=25,
    description="Updated description for accessories"
)
```

#### Delete a Product Category

To delete a product category:

```python
wp.product_categories.delete(25)
```


## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

### Release: 0.2.0
Add support for yoast_wpseo_opengraph-image in the SEO endpoint.
Add support for WooCommerce products and product categories.

### Release: 0.1.3
Add support for slug in get method for posts and pages.