<commit_before>"""
******
Entity
******

The Entity class is the base class for all entities, including Project, Folder
and File, Link, as well as deprecated entity types such as Data, Study, Summary,
etc.

Entities are dictionary-like objects in which both object and dictionary
notation (entity.foo or entity['foo']) can be used interchangeably.

Imports::

    from synapseclient import Project, Folder, File, Link

.. autoclass:: synapseclient.entity.Entity

~~~~~~~
Project
~~~~~~~

.. autoclass:: synapseclient.entity.Project

~~~~~~
Folder
~~~~~~

.. autoclass:: synapseclient.entity.Folder

~~~~
File
~~~~

.. autoclass:: synapseclient.entity.File

~~~~
Link
~~~~

.. autoclass:: synapseclient.entity.Link

~~~~~~~~~~~~
Table Schema
~~~~~~~~~~~~

.. autoclass:: synapseclient.table.Schema


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Properties and annotations, implementation details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In Synapse, entities have both properties and annotations. Properties are used
by the system, whereas annotations are completely user defined. In the Python
client, we try to present this situation as a normal object, with one set of
properties.

Printing an entity will show the division between properties and annotations.::

    print(entity)
<commit_msg>Docs re: changing file names to address SYNPY-301 change actual file name from python client<commit_after>"""
******
Entity
******

The Entity class is the base class for all entities, including Project, Folder
and File, Link, as well as deprecated entity types such as Data, Study, Summary,
etc.

Entities are dictionary-like objects in which both object and dictionary
notation (entity.foo or entity['foo']) can be used interchangeably.

Imports::

    from synapseclient import Project, Folder, File, Link

.. autoclass:: synapseclient.entity.Entity

~~~~~~~
Project
~~~~~~~

.. autoclass:: synapseclient.entity.Project

~~~~~~
Folder
~~~~~~

.. autoclass:: synapseclient.entity.Folder

~~~~
File
~~~~

.. autoclass:: synapseclient.entity.File

Changing File Names
-------------------

A Synapse File Entity has a name separate from the name of the actual file
it represents. When a file is uploaded to Synapse, its filename is fixed,
even though the name of the entity can be changed at any time. Synapse
provides a way to effectively change the filename by setting a special
property called "*fileNameOverride*".

Setting the *fileNameOverride* means that the file will then be downloaded
with the new name.:

>>> e = syn.get(synid)
>>> print(os.path.basename(e.path))  ## prints, e.g., "my_file.txt"
>>> e.fileNameOverride = "my_newname_file.txt"
>>> e = syn.store(e)

Setting *fileNameOverride* will **not** change the name of a copy of the
file that's already downloaded into your local cache. Either rename the
local copy manually or remove it from the cache and re-download.:

>>> syn.cache.remove(e.dataFileHandleId)
>>> e = syn.get(e)
>>> print(os.path.basename(e.path))  ## prints "my_newname_file.txt"

~~~~
Link
~~~~

.. autoclass:: synapseclient.entity.Link

~~~~~~~~~~~~
Table Schema
~~~~~~~~~~~~

.. autoclass:: synapseclient.table.Schema


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Properties and annotations, implementation details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In Synapse, entities have both properties and annotations. Properties are used
by the system, whereas annotations are completely user defined. In the Python
client, we try to present this situation as a normal object, with one set of
properties.

Printing an entity will show the division between properties and annotations.::

    print(entity)

{'fraction_non_alphanumeric': 0.17057220708446866, 'fraction_numerical': 0.0008174386920980927, 'mean_word_length': 4.8548644338118025, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 24, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 3, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2815174', 'n_tokens_mistral': 990, 'n_tokens_neox': 944, 'n_words': 399}