lukhed-x 0.1.0__tar.gz

lukhed_x-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lukhed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lukhed_x-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.1
+Name: lukhed_x
+Version: 0.1.0
+Summary: Custom tweepy wrapper for posting on X. Used by @grindSunday and @popPunkpoets Bots
+Home-page: https://github.com/lukhed/lukhed_x
+Author: lukhed
+Author-email: lukhed.mail@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# lukhed_x
+
+A custom tweepy wrapper for posting on X (formerly Twitter) with built-in key management and enhanced functionality. 
+Used by @grindSunday and @popPunkPoets bots.
+
+## Features
+
+- **Easy X API Integration**: Simplified interface for X API v1 and v2 endpoints
+- **Flexible Key Management**: Store API credentials locally or in GitHub repositories
+- **Post Management**: Create, delete, and manage posts with media support
+- **Image Upload Support**: Easy media attachment for posts
+
+## Installation
+
+```bash
+pip install lukhed_x
+```
+
+## Quick Start
+
+### Initial Setup
+
+```python
+from lukhed_x import X
+
+# First-time setup - this will prompt for your X API credentials
+x_client = X(handle="your_handle", x_api_setup=True)
+```
+
+### Basic Usage
+
+```python
+from lukhed_x import X
+
+# Initialize client (after initial setup)
+x_client = X(handle="your_handle")
+
+# Create a simple tweet
+result = x_client.create_tweet("Hello, world!")
+if not result["error"]:
+    print(f"Tweet posted: {result['url']}")
+    print(f"Tweet ID: {result['tweetID']}")
+
+# Create tweet with image
+result = x_client.create_tweet(
+    "Check out this image!", 
+    image_data="path/to/image.jpg"
+)
+
+# Reply to a tweet
+result = x_client.create_tweet(
+    ".@username Thanks for the great post!",
+    reply_to_tweet_id="1234567890"
+)
+
+# Quote tweet
+result = x_client.create_tweet(
+    "Great point!",
+    quote_tweet_id="1234567890"
+)
+
+# Delete a tweet
+result = x_client.delete_tweet("your_tweet_id")
+```
+
+## X API Setup
+
+Before using lukhed_x, you need to set up an X Developer account:
+
+1. Create a free developer account at [developer.x.com](https://developer.x.com/en)
+2. Create a new app and generate your API credentials
+3. You'll need:
+   - **API Key**
+   - **API Secret** 
+   - **Access Token**
+   - **Access Token Secret**
+
+For detailed instructions, visit: [X API Getting Started Guide](https://docs.x.com/x-api/getting-started/getting-access)
+
+## Key Management Options
+
+lukhed_x supports two key management strategies:
+
+### Local Storage
+```python
+x_client = X(handle="your_handle", key_management="local")
+```
+Stores API credentials in your local file system.
+
+### GitHub Storage (Default)
+```python
+x_client = X(handle="your_handle", key_management="github")
+```
+Stores API credentials in a private GitHub repository, allowing access across different devices. You will need a 
+github access token: 
+[Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+
+## Error Handling
+
+All API methods return a consistent error structure:
+
+```python
+result = x_client.create_tweet("Hello!")
+if result["error"]:
+    print("Function Error:", result["errorData"]["functionError"])
+    print("Tweepy Error:", result["errorData"]["tweepyError"])
+else:
+    print("Success:", result["url"])
+```
+
+## License
+
+This project is licensed under the MIT License.
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.
+
+---
+**Note**: This wrapper is designed for legitimate bot usage and follows X's Terms of Service. 
+Please ensure your bot complies with X's automation rules and rate limits.

lukhed_x-0.1.0/README.md

@@ -0,0 +1,121 @@
+# lukhed_x
+
+A custom tweepy wrapper for posting on X (formerly Twitter) with built-in key management and enhanced functionality. 
+Used by @grindSunday and @popPunkPoets bots.
+
+## Features
+
+- **Easy X API Integration**: Simplified interface for X API v1 and v2 endpoints
+- **Flexible Key Management**: Store API credentials locally or in GitHub repositories
+- **Post Management**: Create, delete, and manage posts with media support
+- **Image Upload Support**: Easy media attachment for posts
+
+## Installation
+
+```bash
+pip install lukhed_x
+```
+
+## Quick Start
+
+### Initial Setup
+
+```python
+from lukhed_x import X
+
+# First-time setup - this will prompt for your X API credentials
+x_client = X(handle="your_handle", x_api_setup=True)
+```
+
+### Basic Usage
+
+```python
+from lukhed_x import X
+
+# Initialize client (after initial setup)
+x_client = X(handle="your_handle")
+
+# Create a simple tweet
+result = x_client.create_tweet("Hello, world!")
+if not result["error"]:
+    print(f"Tweet posted: {result['url']}")
+    print(f"Tweet ID: {result['tweetID']}")
+
+# Create tweet with image
+result = x_client.create_tweet(
+    "Check out this image!", 
+    image_data="path/to/image.jpg"
+)
+
+# Reply to a tweet
+result = x_client.create_tweet(
+    ".@username Thanks for the great post!",
+    reply_to_tweet_id="1234567890"
+)
+
+# Quote tweet
+result = x_client.create_tweet(
+    "Great point!",
+    quote_tweet_id="1234567890"
+)
+
+# Delete a tweet
+result = x_client.delete_tweet("your_tweet_id")
+```
+
+## X API Setup
+
+Before using lukhed_x, you need to set up an X Developer account:
+
+1. Create a free developer account at [developer.x.com](https://developer.x.com/en)
+2. Create a new app and generate your API credentials
+3. You'll need:
+   - **API Key**
+   - **API Secret** 
+   - **Access Token**
+   - **Access Token Secret**
+
+For detailed instructions, visit: [X API Getting Started Guide](https://docs.x.com/x-api/getting-started/getting-access)
+
+## Key Management Options
+
+lukhed_x supports two key management strategies:
+
+### Local Storage
+```python
+x_client = X(handle="your_handle", key_management="local")
+```
+Stores API credentials in your local file system.
+
+### GitHub Storage (Default)
+```python
+x_client = X(handle="your_handle", key_management="github")
+```
+Stores API credentials in a private GitHub repository, allowing access across different devices. You will need a 
+github access token: 
+[Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+
+## Error Handling
+
+All API methods return a consistent error structure:
+
+```python
+result = x_client.create_tweet("Hello!")
+if result["error"]:
+    print("Function Error:", result["errorData"]["functionError"])
+    print("Tweepy Error:", result["errorData"]["tweepyError"])
+else:
+    print("Success:", result["url"])
+```
+
+## License
+
+This project is licensed under the MIT License.
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.
+
+---
+**Note**: This wrapper is designed for legitimate bot usage and follows X's Terms of Service. 
+Please ensure your bot complies with X's automation rules and rate limits.

lukhed_x-0.1.0/lukhed_x/__init__.py

@@ -0,0 +1,3 @@
+from .x_api import X
+
+__all__ = ["X"]

lukhed_x-0.1.0/lukhed_x/x_api.py

@@ -0,0 +1,267 @@
+from typing import Optional
+from lukhed_basic_utils.githubCommon import KeyManager
+from lukhed_basic_utils import osCommon as osC
+import tweepy
+import time
+import re
+
+# https://docs.tweepy.org/en/v3.10.0/api.html
+# https://developer.twitter.com/en/docs/twitter-api/v1/rate-limits
+
+
+
+class X():
+    def __init__(self, handle, key_management='github', x_api_setup=False):
+        """
+        This class is a custom tweepy wrapper for posting on X (formerly Twitter). It includes key management and 
+        basic endpoints.
+
+        Parameters
+        ----------
+        handle : str
+            The Twitter handle to use for API requests.
+        key_management : str, optional
+            The strategy key management strategy to use. Options are:
+            'local' - stores/retrieve your api key on your local hard drive (working directory)
+            'github' - stores/retrieves your api key in a private repo (helpful to allow access across different hardware)
+            Default is 'github'.
+        x_api_setup : bool, optional
+            Set this to true for initial setup of the X API credentials. You will be prompted to enter your 
+            API information from https://developer.x.com/en.
+         """
+
+        # class variables
+        osC.check_create_dir_structure(['lukhedConfig'])
+        self.key_management = key_management.lower()
+        self._token_file_path = osC.create_file_path_string(['lukhedConfig', 'localTokenFile.json'])
+        self.current_handle = handle
+        self._parse_handle()
+        self._key_data = {}
+        self.current_version = 2
+
+        # Objects used
+        self.tweepy_api: Optional[tweepy.Client] = None
+        self._kM: Optional[KeyManager] = None
+
+        # One time setup option
+        if x_api_setup:
+            self._x_api_setup()
+
+        # Load access data
+        self._check_create_km()
+
+        self._tweepy_generate_api(self.current_version)
+    
+    def _x_api_setup(self):
+        print("This is the lukhed setup for the X API. If you haven't already, you first need to setup an"
+              " X api developer acccount (free here: https://developer.x.com/en). To continue, you need the following"
+              " from the setup:\n"
+              "1. Access Token\n"
+              "2. Access Token Secret\n"
+              "3. Api Key\n"
+              "4. Api Secret\n"
+              "If you don't know how to get these, you can find instructions here:\n"
+              "https://docs.x.com/x-api/getting-started/getting-access")
+        
+        if input("\n\nAre you ready to continue (y/n)?") == 'n':
+            print("OK, come back when you have setup your developer account")
+            quit()
+
+        access_token = input("Paste your access token then press enter:\n").replace(" ", "")
+        access_token_secret = input("Paste your access token secret then press enter:\n").replace(" ", "")
+        api_key = input("Paste your API key here:\n").replace(" ", "")
+        api_secret = input("Paste your API secret here:\n").replace(" ", "")
+
+        self._key_data[self.current_handle] = dict()
+        self._key_data[self.current_handle]['accessToken'] = access_token
+        self._key_data[self.current_handle]['accessTokenSecret'] = access_token_secret
+        self._key_data[self.current_handle]['apiKey'] = api_key
+        self._key_data[self.current_handle]['apiSecret'] = api_secret
+
+        print("\n\nThe X portion is complete! Now setting up key management with lukhed library...")
+        self._kM = KeyManager('xApi', config_file_preference=self.key_management, 
+                             provide_key_data=self._key_data)
+
+    def _check_create_km(self):
+        if self._kM is None:
+            # get the key data previously setup
+            self._kM = KeyManager('xApi', config_file_preference=self.key_management)
+            self._key_data = self._kM.key_data
+    
+    def _parse_handle(self):
+        # accept a handle with or without the @symbol
+        if "@" not in self.current_handle:
+            self.current_handle = "@" + self.current_handle
+
+    def _tweepy_generate_api(self, version):
+        self.current_version = version
+        key_data = self._key_data[self.current_handle]
+        if version == 2:
+            """
+            https://docs.tweepy.org/en/stable/authentication.html#id3
+            need user context to unlock all methods
+            """
+            return tweepy.Client(consumer_key=key_data["apiKey"],
+                                 consumer_secret=key_data["apiSecret"],
+                                 access_token=key_data["accessToken"],
+                                 access_token_secret=key_data["accessTokenSecret"])
+        elif version == 1:
+            auth = tweepy.OAuthHandler(key_data['apiKey'], key_data['apiSecret'])
+            auth.set_access_token(key_data['accessToken'], key_data['accessTokenSecret'])
+
+            return tweepy.API(auth)
+        else:
+            return None
+
+    def _check_create_tweepy_api(self, version_int):
+        """
+        This function creates the tweepy api based on the twitter API version requested.
+        The free twitter API currently supports v2 endpoints but allows access to some v1 endpoints still
+
+        :param version_int:     int(), 1 or 2
+        :return:
+        """
+        # Create a twitter API if one does not exist or if the current api version is not correct for the method
+        if self.tweepy_api is None or version_int != self.current_version:
+            self.tweepy_api = self._tweepy_generate_api(version_int)
+
+    def _try_print_tweepy_exception(self, tweepy_exception):
+        """
+        :param tweepy_exception:
+        :return:
+        """
+        print("Trying to print exception:")
+
+        try:
+            print(tweepy_exception)
+            tweepy_defined_error_message = tweepy_exception
+        except:
+            tweepy_defined_error_message = "failed getting the tweepy defined error message"
+            print(tweepy_defined_error_message)
+
+        return tweepy_defined_error_message
+
+    def _parse_image_data(self, image_data):
+        media_ids = []
+        if type(image_data) is list:
+            for i in image_data:
+                media = self.tweepy_api.media_upload(i)
+                media_ids.append(media.media_id)
+        else:
+            media = self.tweepy_api.media_upload(image_data)
+            media_ids.append(media.media_id)
+
+        return media_ids
+
+    #######################
+    # Free with API
+    def create_tweet(self, tweet_message_str, reply_to_tweet_id=None, image_data=None, quote_tweet_id=None):
+        """
+        This function creates a tweet. It uses v2 twitter endpoints and comes with the Basic (free) plan. All accounts
+        can use this functionality.
+
+        Tweepy doc is here:
+        https://docs.tweepy.org/en/stable/client.html#tweepy.Client.create_tweet
+
+
+        :param tweet_message_str:           text you want to tweet
+
+        :param reply_to_tweet_id:           tweet ID you want to reply to. Note: if this is supplied,
+                                            @[handle_replying_to] must be in tweet text for it to show up in the
+                                            replies
+
+        :param image_data:                  list or image. Image can be path to image or actual image
+
+        :param quote_tweet_id:              to quote tweet, put the id here
+
+        :return: success bool and tweepy response if applicable
+        """
+
+        try:
+            if image_data is not None:
+                self._check_create_tweepy_api(1)
+                media_ids = self._parse_image_data(image_data)
+            else:
+                media_ids = None
+
+            self._check_create_tweepy_api(2)
+            status_update = self.tweepy_api.create_tweet(text=tweet_message_str, in_reply_to_tweet_id=reply_to_tweet_id,
+                                                  media_ids=media_ids, quote_tweet_id=quote_tweet_id)
+
+            tweet_url = "https://twitter.com/" + self.current_handle.replace("@", "") + "/status/" + \
+                        status_update.data['id']
+            tweet_id = status_update.data['id']
+        except Exception as e:
+            function_defined_error_message = "Failed while trying to tweet. self.tweepy_api.create_tweet"
+            print(function_defined_error_message)
+
+            tweepy_defined_error_message = self._try_print_tweepy_exception(e)
+
+            return {"error": True,
+                    "twitterResponse": None,
+                    "errorData": {"functionError": function_defined_error_message,
+                                  "tweepyError": tweepy_defined_error_message}}
+
+        return {"error": False,
+                "twitterResponse": status_update,
+                "errorData": None,
+                "url": tweet_url,
+                "tweetID": tweet_id,
+                "tweetHandle": self.current_handle}
+
+    def delete_tweet(self, tweet_id):
+        """
+        This function deletes a tweet. It uses v2 twitter endpoints and comes with the Basic (free) plan. All accounts
+        can use this functionality.
+
+        Tweepy doc is here:
+        https://docs.tweepy.org/en/stable/client.html#tweepy.Client.delete_tweet
+
+        :param tweet_id:
+        :return:
+        """
+
+        self._check_create_tweepy_api(2)
+        try:
+            twitter_response = self.tweepy_api.delete_tweet(tweet_id)
+        except Exception as e:
+            function_defined_error_message = "Failed while trying to delete tweet. self.tweepy_api.delete_tweet"
+            print(function_defined_error_message)
+            tweepy_defined_error_message = self._try_print_tweepy_exception(e)
+
+            return {"error": True,
+                    "twitterResponse": None,
+                    "errorData": {"functionError": function_defined_error_message,
+                                  "tweepyError": tweepy_defined_error_message}}
+
+        return {"error": False,
+                "twitterResponse": twitter_response,
+                "errorData": None}
+
+    def get_my_user_info(self):
+        """
+        This function gets a variety of information about the current authorized user.
+        It uses v2 twitter endpoints and comes with the Basic (free) plan. All accounts can use this functionality.
+
+        Tweepy doc is here:
+        https://docs.tweepy.org/en/stable/client.html#tweepy.Client.get_me
+
+        :return:
+        """
+
+        self._check_create_tweepy_api(2)
+        try:
+            twitter_response = self.tweepy_api.get_me()
+        except Exception as e:
+            function_defined_error_message = "Failed while trying lookup user. self.tweepy_api.get_user"
+            print(function_defined_error_message)
+            tweepy_defined_error_message = self._try_print_tweepy_exception(e)
+
+            return {"error": True,
+                    "twitterResponse": None,
+                    "errorData": {"functionError": function_defined_error_message,
+                                  "tweepyError": tweepy_defined_error_message}}
+
+        return {"error": False,
+                "twitterResponse": twitter_response,
+                "errorData": None}

lukhed_x-0.1.0/lukhed_x.egg-info/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.1
+Name: lukhed-x
+Version: 0.1.0
+Summary: Custom tweepy wrapper for posting on X. Used by @grindSunday and @popPunkpoets Bots
+Home-page: https://github.com/lukhed/lukhed_x
+Author: lukhed
+Author-email: lukhed.mail@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# lukhed_x
+
+A custom tweepy wrapper for posting on X (formerly Twitter) with built-in key management and enhanced functionality. 
+Used by @grindSunday and @popPunkPoets bots.
+
+## Features
+
+- **Easy X API Integration**: Simplified interface for X API v1 and v2 endpoints
+- **Flexible Key Management**: Store API credentials locally or in GitHub repositories
+- **Post Management**: Create, delete, and manage posts with media support
+- **Image Upload Support**: Easy media attachment for posts
+
+## Installation
+
+```bash
+pip install lukhed_x
+```
+
+## Quick Start
+
+### Initial Setup
+
+```python
+from lukhed_x import X
+
+# First-time setup - this will prompt for your X API credentials
+x_client = X(handle="your_handle", x_api_setup=True)
+```
+
+### Basic Usage
+
+```python
+from lukhed_x import X
+
+# Initialize client (after initial setup)
+x_client = X(handle="your_handle")
+
+# Create a simple tweet
+result = x_client.create_tweet("Hello, world!")
+if not result["error"]:
+    print(f"Tweet posted: {result['url']}")
+    print(f"Tweet ID: {result['tweetID']}")
+
+# Create tweet with image
+result = x_client.create_tweet(
+    "Check out this image!", 
+    image_data="path/to/image.jpg"
+)
+
+# Reply to a tweet
+result = x_client.create_tweet(
+    ".@username Thanks for the great post!",
+    reply_to_tweet_id="1234567890"
+)
+
+# Quote tweet
+result = x_client.create_tweet(
+    "Great point!",
+    quote_tweet_id="1234567890"
+)
+
+# Delete a tweet
+result = x_client.delete_tweet("your_tweet_id")
+```
+
+## X API Setup
+
+Before using lukhed_x, you need to set up an X Developer account:
+
+1. Create a free developer account at [developer.x.com](https://developer.x.com/en)
+2. Create a new app and generate your API credentials
+3. You'll need:
+   - **API Key**
+   - **API Secret** 
+   - **Access Token**
+   - **Access Token Secret**
+
+For detailed instructions, visit: [X API Getting Started Guide](https://docs.x.com/x-api/getting-started/getting-access)
+
+## Key Management Options
+
+lukhed_x supports two key management strategies:
+
+### Local Storage
+```python
+x_client = X(handle="your_handle", key_management="local")
+```
+Stores API credentials in your local file system.
+
+### GitHub Storage (Default)
+```python
+x_client = X(handle="your_handle", key_management="github")
+```
+Stores API credentials in a private GitHub repository, allowing access across different devices. You will need a 
+github access token: 
+[Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+
+## Error Handling
+
+All API methods return a consistent error structure:
+
+```python
+result = x_client.create_tweet("Hello!")
+if result["error"]:
+    print("Function Error:", result["errorData"]["functionError"])
+    print("Tweepy Error:", result["errorData"]["tweepyError"])
+else:
+    print("Success:", result["url"])
+```
+
+## License
+
+This project is licensed under the MIT License.
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.
+
+---
+**Note**: This wrapper is designed for legitimate bot usage and follows X's Terms of Service. 
+Please ensure your bot complies with X's automation rules and rate limits.

lukhed_x-0.1.0/lukhed_x.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+setup.py
+lukhed_x/__init__.py
+lukhed_x/x_api.py
+lukhed_x.egg-info/PKG-INFO
+lukhed_x.egg-info/SOURCES.txt
+lukhed_x.egg-info/dependency_links.txt
+lukhed_x.egg-info/requires.txt
+lukhed_x.egg-info/top_level.txt

lukhed_x-0.1.0/lukhed_x.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lukhed_x-0.1.0/lukhed_x.egg-info/requires.txt

@@ -0,0 +1,2 @@
+lukhed-basic-utils>=1.6.4
+tweepy>=4.16.0

lukhed_x-0.1.0/lukhed_x.egg-info/top_level.txt

@@ -0,0 +1 @@
+lukhed_x

lukhed_x-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lukhed_x-0.1.0/setup.py

@@ -0,0 +1,24 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="lukhed_x",
+    version="0.1.0",
+    description="Custom tweepy wrapper for posting on X. Used by @grindSunday and @popPunkpoets Bots",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="lukhed",
+    author_email="lukhed.mail@gmail.com",
+    url="https://github.com/lukhed/lukhed_x",
+    packages=find_packages(),
+    include_package_data=True,  # Ensures MANIFEST.in is used
+    python_requires=">=3.9",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    install_requires=[
+        "lukhed-basic-utils>=1.6.4",
+        "tweepy>=4.16.0",
+    ],
+)