Skip to content

file

File

Bases: MdObj

A stored file.

This is typically not needed by the end-user.

Source code in mkreports/md/file.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
@register_md("File")
class File(MdObj):
    """
    A stored file.

    This is typically not needed by the end-user.
    """

    path: Path
    allow_copy: bool
    use_hash: bool
    _hash: Optional[str] = None

    def __init__(
        self,
        path: Union[str, Path],
        page_info: PageInfo,
        allow_copy: bool = True,
        use_hash: bool = False,
    ) -> None:
        """
        Store a file in the page-store.

        Args:
            path (Union[str, Path]): Path to the file,
                relative to current directory or absolute.
            page_info (PageInfo): PageInfo for the page where the file should be stored.
            allow_copy (bool): Is the file allowed to be copied? Otherwise, original
                location is used.
            use_hash (bool): If copy is allowed, renames the file to include the file hash.
        """
        super().__init__()

        # store path needs to be set
        assert page_info.store_path is not None

        # set the existing attributes
        self.allow_copy = allow_copy
        self.use_hash = use_hash
        self.store_path = page_info.store_path

        # for the path we first have to see if they will be copied
        self.path = Path(path).absolute()

        if self.allow_copy:

            if self.use_hash:
                # we calculate the hash of the file to be ingested
                new_path = self.store_path / (
                    true_stem(self.path) + "-" + self.hash + "".join(self.path.suffixes)
                )
            else:
                new_path = self.store_path / self.path.name

            # now see if we move or copy the file
            new_path.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy(path, new_path)
            self.path = new_path

        # it returns nothing
        self._body = None
        self._back = None
        self._settings = None

    @property
    def hash(self) -> str:
        """
        Calculate the hash of the file.

        Returns:
            str: Md5-hash as a string.

        """
        if self._hash is None:
            self._hash = md5_hash_file(self.path)
        return self._hash

__init__(path, page_info, allow_copy=True, use_hash=False)

Store a file in the page-store.

Parameters:

Name Type Description Default
path Union[str, Path]

Path to the file, relative to current directory or absolute.

 required
page_info PageInfo

PageInfo for the page where the file should be stored.

 required
allow_copy bool

Is the file allowed to be copied? Otherwise, original location is used.

 True
use_hash bool

If copy is allowed, renames the file to include the file hash.

 False
Source code in mkreports/md/file.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def __init__(
    self,
    path: Union[str, Path],
    page_info: PageInfo,
    allow_copy: bool = True,
    use_hash: bool = False,
) -> None:
    """
    Store a file in the page-store.

    Args:
        path (Union[str, Path]): Path to the file,
            relative to current directory or absolute.
        page_info (PageInfo): PageInfo for the page where the file should be stored.
        allow_copy (bool): Is the file allowed to be copied? Otherwise, original
            location is used.
        use_hash (bool): If copy is allowed, renames the file to include the file hash.
    """
    super().__init__()

    # store path needs to be set
    assert page_info.store_path is not None

    # set the existing attributes
    self.allow_copy = allow_copy
    self.use_hash = use_hash
    self.store_path = page_info.store_path

    # for the path we first have to see if they will be copied
    self.path = Path(path).absolute()

    if self.allow_copy:

        if self.use_hash:
            # we calculate the hash of the file to be ingested
            new_path = self.store_path / (
                true_stem(self.path) + "-" + self.hash + "".join(self.path.suffixes)
            )
        else:
            new_path = self.store_path / self.path.name

        # now see if we move or copy the file
        new_path.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy(path, new_path)
        self.path = new_path

    # it returns nothing
    self._body = None
    self._back = None
    self._settings = None

hash()

Calculate the hash of the file.

Returns:

Name Type Description
str str

Md5-hash as a string.
Source code in mkreports/md/file.py 
150
151
152
153
154
155
156
157
158
159
160
161
@property
def hash(self) -> str:
    """
    Calculate the hash of the file.

    Returns:
        str: Md5-hash as a string.

    """
    if self._hash is None:
        self._hash = md5_hash_file(self.path)
    return self._hash

md5_hash_file(path)

Get md5 hash of a file.

Parameters:

Name Type Description Default
path Path

Absolute path or relative to current directory of the file.

 required

Returns:

Name Type Description
str str

The md5 hash of the file.
Source code in mkreports/md/file.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def md5_hash_file(path: Path) -> str:
    """
    Get md5 hash of a file.

    Args:
        path (Path): Absolute path or relative to current directory of the file.

    Returns:
        str: The md5 hash of the file.

    """
    m = hashlib.md5()
    with path.open("rb") as f:
        m.update(f.read())

    return m.hexdigest()

relpath_html(target, page_path)

Relative path as to be used for html. This is a bit more complicated, as some markdown pages are encoded as a directory (with implicit index.html being called).

The paths can be relative or absolute. If relative, should be relative to same directory.

Parameters:

Name Type Description Default
target Path

The target path

 required
page_path Path

Path of the current page.

 required

Returns:

Name Type Description
str str

Relative path as a string.
Source code in mkreports/md/file.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def relpath_html(target: Path, page_path: Path) -> str:
    """
    Relative path as to be used for html. This is a bit more complicated,
    as some markdown pages are encoded as a directory (with implicit index.html
    being called).

    The paths can be relative or absolute. If relative, should be relative to
    same directory.

    Args:
        target (Path): The target path
        page_path (Path): Path of the current page.

    Returns:
        str: Relative path as a string.

    """
    if page_path.stem == "index":
        # here, for translating to html, this path is referred to as its parent
        return relpath(target, page_path.parent)
    else:
        # for translating to html, will be converted to path.parent / path.stem / index.html
        return relpath(target, page_path)

store_asset_relpath(asset_path_mkreports, page_info)

Store an asset and return relative path to it.

Parameters:

Name Type Description Default
asset_path Path

Relative asset path inside 'mkreports'

 required
page_info PageInfo

PageInfo for the page in use

 required

Returns:

Name Type Description
str str

Path to the asset as it should be used from html
Source code in mkreports/md/file.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def store_asset_relpath(asset_path_mkreports: Path, page_info: PageInfo) -> str:
    """
    Store an asset and return relative path to it.

    Args:
        asset_path (Path): Relative asset path inside 'mkreports'
        page_info (PageInfo): PageInfo for the page in use

    Returns:
        str: Path to the asset as it should be used from html
    """
    assert page_info.javascript_path is not None
    assert page_info.page_path is not None
    asset_path_report_abs = (
        page_info.javascript_path / "assets" / asset_path_mkreports.name
    )
    asset_path_report_abs.parent.mkdir(parents=True, exist_ok=True)
    shutil.copy(
        imp_res.files("mkreports") / "assets" / asset_path_mkreports,
        asset_path_report_abs,
    )
    return relpath_html(asset_path_report_abs, page_info.page_path)

true_stem(path)

True stem of a path, without all suffixes, not just last.

Source code in mkreports/md/file.py 
14
15
16
def true_stem(path: Path) -> str:
    """True stem of a path, without all suffixes, not just last."""
    return path.name[: -(len("".join(path.suffixes)))]