<commit_before>import os
import random
import string
from stat import S_IRWXU

from abc import ABCMeta, abstractmethod


class Connection():
    __metaclass__ = ABCMeta

    def finalize(self):
        pass

    @abstractmethod
    def open(self, path, mode):
        pass

    @abstractmethod
    def mkdir(self, directory, recursive=False):
        pass

    @abstractmethod
    def stat(self, path):
        pass

    @abstractmethod
    def which(self, executable):
        pass

    @abstractmethod
    def exists(self, path):
        pass

    @abstractmethod
    def user(self):
        pass

    @abstractmethod
    def user_home(self):
        pass

    @abstractmethod
    def copy(self, msg, source, dest):
        pass

    @abstractmethod
    def download(self, msg, source, dest):
        pass

    @abstractmethod
    def chmod(self, path, new_mode, append=False):
        pass

    @abstractmethod
    def chown(self, path, uid=None, guid=None):
        pass

    @abstractmethod
    def get_users(self):
        pass

    @abstractmethod
    def rm(self, path):
        pass

    @abstractmethod
    def get_groups(self):
        pass

    def ensure_path_exists(self, path):
        if self.exists(path):
            return

        self.mkdir(path, recursive=True)
        self.chmod(path, S_IRWXU)

    def mktempdir(self, prefix):
        user = self.user()
        users = self.get_users()
        group = self.get_groups()

        suffix = ''.join(random.choice(string.lowercase) for i in range(8))
        path = os.path.join("/var/tmp", prefix + "-" + suffix)

        self.mkdir(path)
        self.chmod(path, S_IRWXU)

        return path
<commit_msg>Document connection class for need_io documentation<commit_after>import os
import random
import string
from stat import S_IRWXU

from abc import ABCMeta, abstractmethod


class Connection():
    __metaclass__ = ABCMeta

    def finalize(self):
        pass

    @abstractmethod
    def open(self, path, mode):
        """Open a file

        open files works as python's builtin method. Make sure that the 
        path exists on the host where the file will be opend (remote + local)

        Args:
            path:    Path to the file which should be opend
            mode:    Mode in which the file should be opened

            TODO: Add link to builtin method

        Returns:
            The file object for the given path

        Throws:
            Can throw IOError
        """
        pass

    @abstractmethod
    def mkdir(self, directory, recursive=False):
        """Creates a new directory

        Creates one or more directories.

        Args:
            directory: The path which should be created
            recursive: If True the path will be created recursivly as required
        """
        pass

    @abstractmethod
    def stat(self, path):
        """Get stat of a inode

        Args:
            path: path to stat

        Returns:
            the stats object
        """
        pass

    @abstractmethod
    def which(self, executable):
        """Get the path of a executable

        This will return the path to the search exectuable if available

        Args:
            executable:     The application which is searched

        Returns:
            The path to the executable if found, None otherwise
        """
        pass

    @abstractmethod
    def exists(self, path):
        """Check if a path exists.

        Args:
            path:   Path which should be checked

        Returns:
            True if found, False otherwise
        """
        pass

    @abstractmethod
    def user(self):
        """Get current username

        This method also returns the correct user name if a remote host
        is used.

        Returns:
            The name of the current user
        """
        pass

    @abstractmethod
    def user_home(self):
        """Get current user home

        This method also returns the correct user home if a remote host
        is used.

        Returns:
            The path to home for the current user
        """
        pass

    # FIXME: Make this more clear whats happening
    @abstractmethod
    def copy(self, msg, source, dest):
        pass

    @abstractmethod
    def download(self, msg, source, dest):
        pass

    @abstractmethod
    def chmod(self, path, new_mode, append=False):
        """Set permissions for a path

        Without append=True this function overwrites existing
        permissions.

        Args:
            path:       Path where permission should be changed
            new_mode:   New mode for the path
            append:     Just add new permissions to old one
        """
        pass

    @abstractmethod
    def chown(self, path, uid=None, guid=None):
        """Set ownership of a path

        Only change the user id is working like

        :: 

            self.chown(some_path, uid=1000)

        Args:
            path:       The patch which should be changed
            uid:        User id which should own the file
            guid:       Group user id which should be owned
        """
        pass

    @abstractmethod
    def get_users(self):
        """Get all users defined

        This method fetches all users defined from the used host (remote +
        local) and returns them.

        Returns:
            A list of all users defined
        """
        pass

    @abstractmethod
    def rm(self, path):
        """Delete a path

        Args:
            path:   Path which should be deleted
        """
        pass

    @abstractmethod
    def get_groups(self):
        """Get all groups with extradata

        This method fetches groups from the used host (remote + local) and
        returns them.

        Returns:
            Returns a list of groups defined in the host system
        """
        pass

    def ensure_path_exists(self, path):
        """Make sure a path exsists if not create it

        When a path is not exisiting, it will be recursivly created

        Args:
            path: The path which should exist
        """
        if self.exists(path):
            return

        self.mkdir(path, recursive=True)
        self.chmod(path, S_IRWXU)

    def mktempdir(self, prefix):
        """Creates a temporary directory under /var/tmp/<user>

        Args:
            prefix: Prefix for the temprary directory (eg. xii -> /var/tmp/xii-2d72ddk9d3)

        Returns:
            The path for the new created directory
        """

        user = self.user()
        users = self.get_users()
        group = self.get_groups()

        suffix = ''.join(random.choice(string.lowercase) for i in range(8))
        path = os.path.join("/var/tmp", prefix + "-" + suffix)

        self.mkdir(path)
        self.chmod(path, S_IRWXU)

        return path

{'fraction_non_alphanumeric': 0.07077826725403819, 'fraction_numerical': 0.0016152716593245229, 'mean_word_length': 1.7822712418300655, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5793192', 'n_tokens_mistral': 1866, 'n_tokens_neox': 1770, 'n_words': 674}